API Reference

Webhooks

API reference for outgoing webhooks - creating JSON, Slack and Discord webhooks, rotating signing secrets, sending tests and reading or redelivering deliveries.

Last updated

Webhooks send panel events to another service: signed JSON for your own code, or a chat message for Slack or Discord. Each event becomes one delivery per webhook that wants it, kept in the database so it survives a restart and retried when it fails. A delivery that gets no 2xx answer within 10 seconds is retried after 1 minute, 5 minutes and 30 minutes.

The payload, headers and how to verify the X-VaultPanel-Signature of a JSON delivery are described in Webhooks. Webhooks that carry a plugin's events are managed on the plugin instead; see Plugins.

MethodPathDescription
GET/api/v1/webhooksList webhooks
POST/api/v1/webhooksCreate a webhook
GET/api/v1/webhooks/:idGet a webhook
PATCH/api/v1/webhooks/:idUpdate a webhook
DELETE/api/v1/webhooks/:idDelete a webhook
POST/api/v1/webhooks/:id/testSend a test
GET/api/v1/webhooks/:id/deliveriesList deliveries
POST/api/v1/webhooks/:id/deliveries/:deliveryId/redeliverRedeliver

Events

EventWhen
backup.succeededA backup finished.
backup.failedA backup failed.
restore.succeededA restore finished.
restore.failedA restore failed.
cron.failedA cron job failed or timed out.
deployment.succeededA deployment went live.
deployment.failedA deployment failed.
alert.firingAn alert started firing.
alert.resolvedAn alert resolved.
server.offlineA server went offline.
server.onlineA server came back online.
ssl.expiringAn SSL certificate is close to expiring.
ssl.expiredAn SSL certificate expired.
ssl.renew_failedAutomatic SSL renewal failed.

Test deliveries use the event webhook.test.

The webhook object

FieldTypeDescription
id, namestringThe webhook.
hoststringWhere it sends, such as https://hooks.slack.com. Lists never include the full URL: chat webhook URLs are secrets.
urlstringOnly in Get a webhook.
formatstringjson (signed), slack or discord.
eventsstring[]The events it receives.
enabledbooleanPaused when false.
lastDeliveryobject or null{ at, status }.
createdAt, updatedAtstringTimestamps.

List webhooks

GET/api/v1/webhooks
Auth
Session cookie (+ CSRF token) or API token
Permission
webhooks.manage
Token scope
manage

Returns your webhooks a page at a time, without plugin webhooks.

Query parameters

NameTypeRequiredDescription
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
sort, orderstringNoname (default) or createdAt; asc (default) or desc.

Example request

curl https://panel.example.com/api/v1/webhooks \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.webhooks.list();

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "4d5e6f7a-…",
        "name": "Ops channel",
        "host": "https://hooks.slack.com",
        "format": "slack",
        "events": ["backup.failed", "alert.firing", "server.offline"],
        "enabled": true,
        "lastDelivery": { "at": "2026-11-10T09:55:01.000Z", "status": "succeeded" },
        "createdAt": "2026-10-04T12:00:00.000Z",
        "updatedAt": "2026-10-04T12:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
  },
  "message": "OK",
  "requestId": "…"
}

Create a webhook

POST/api/v1/webhooks
Auth
Session cookie (+ CSRF token) or API token
Permission
webhooks.manage
Token scope
manage

Creates a webhook and returns its signing secret (whsec_…), which is shown only in this response. JSON deliveries are signed with it; Slack and Discord messages are unsigned, since their URL is the secret.

Request body

FieldTypeRequiredDescription
namestringYesUp to 100 characters.
urlstringYesA full http or https URL, up to 2000 characters, without user:password@.
formatstringNojson (default), slack or discord.
eventsstring[]YesAt least one event.
enabledbooleanNoDefault true.

Deliveries to private network addresses are refused unless the panel's .env sets VAULTPANEL_WEBHOOK_ALLOW_PRIVATE=true.

Example request

curl https://panel.example.com/api/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy tracker",
    "url": "https://hooks.example.com/vaultpanel",
    "format": "json",
    "events": ["deployment.succeeded", "deployment.failed"]
  }'
const { webhook, secret } = await panel.webhooks.create({
  name: 'Deploy tracker',
  url: 'https://hooks.example.com/vaultpanel',
  format: 'json',
  events: ['deployment.succeeded', 'deployment.failed'],
});
// Store `secret` now: it is not shown again.

Response 201 Created

{
  "success": true,
  "data": {
    "webhook": {
      "id": "4d5e6f7a-…",
      "name": "Deploy tracker",
      "host": "https://hooks.example.com",
      "format": "json",
      "events": ["deployment.succeeded", "deployment.failed"],
      "enabled": true,
      "lastDelivery": null
    },
    "secret": "whsec_…"
  },
  "message": "Webhook added",
  "requestId": "…"
}

Errors

StatusCodeWhen
422VALIDATION_ERRORNot a full http or https URL, credentials in the URL, no events, or an unknown event.

Get a webhook

GET/api/v1/webhooks/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
webhooks.manage
Token scope
manage

Returns the webhook with its full url. The secret is never returned again.

Example request

curl https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const webhook = await panel.webhooks.get(webhookId);

Response 200 OK: the webhook object with url.

Errors

StatusCodeWhen
404NOT_FOUNDNo webhook with this id.
409PLUGIN_WEBHOOKIt carries a plugin's events: manage it on the plugin.

Update a webhook

PATCH/api/v1/webhooks/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
webhooks.manage
Token scope
manage

Changes any of name, url, format, events and enabled. With rotateSecret: true, a new signing secret replaces the old one at once and is returned in this response only. Send at least one change.

Example request

curl https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "rotateSecret": true }'
const { webhook, secret } = await panel.webhooks.update(webhookId, { rotateSecret: true });

Response 200 OK: { webhook }, plus secret when it was rotated; message Saved.

Errors

StatusCodeWhen
404NOT_FOUNDNo webhook with this id.
409PLUGIN_WEBHOOKIt carries a plugin's events.
422VALIDATION_ERRORNothing to update, or an invalid field.

Delete a webhook

DELETE/api/v1/webhooks/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
webhooks.manage
Token scope
manage

Deletes the webhook.

Example request

curl https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
await panel.webhooks.remove(webhookId);

Response 200 OK: data is null, message Webhook deleted.

Send a test

POST/api/v1/webhooks/:id/test
Auth
Session cookie (+ CSRF token) or API token
Permission
webhooks.manage
Token scope
manage

Sends a webhook.test event now, once, and returns the delivery with its outcome. A failed test is not retried.

Example request

curl https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a/test \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { delivery } = await panel.webhooks.test(webhookId);
console.log(delivery.status, delivery.responseStatus);

Response 200 OK

{
  "success": true,
  "data": {
    "delivery": {
      "id": "9a0b1c2d-…",
      "webhookId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
      "event": "webhook.test",
      "status": "succeeded",
      "attempts": 1,
      "nextAttemptAt": null,
      "responseStatus": 200,
      "error": null,
      "durationMs": 184,
      "payload": {
        "event": "webhook.test",
        "occurredAt": "2026-11-10T11:30:00.000Z",
        "data": { "webhook": { "id": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a", "name": "Deploy tracker" }, "message": "This is a test from VaultPanel." }
      },
      "createdAt": "2026-11-10T11:30:00.000Z",
      "deliveredAt": "2026-11-10T11:30:00.000Z"
    }
  },
  "message": "OK",
  "requestId": "…"
}

List deliveries

GET/api/v1/webhooks/:id/deliveries
Auth
Session cookie (+ CSRF token) or API token
Permission
webhooks.manage
Token scope
manage

Returns the webhook's deliveries, newest first, with their payloads and outcomes. Deliveries are kept for 30 days.

Query parameters

NameTypeRequiredDescription
statusstringNopending (still being tried), succeeded or failed.
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
orderstringNodesc (default) or asc by creation time.

Example request

curl "https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a/deliveries?status=failed" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.webhooks.deliveries(webhookId, { status: 'failed' });

Response 200 OK: { items, pagination } of deliveries, as in Send a test.

Redeliver

POST/api/v1/webhooks/:id/deliveries/:deliveryId/redeliver
Auth
Session cookie (+ CSRF token) or API token
Permission
webhooks.manage
Token scope
manage

Sends a finished delivery again, now, with the same payload, and returns its new outcome.

Example request

curl https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a/deliveries/9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d/redeliver \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { delivery } = await panel.request('POST', `/webhooks/${webhookId}/deliveries/${deliveryId}/redeliver`);

Response 200 OK: { delivery }.

Errors

StatusCodeWhen
404NOT_FOUNDNo such webhook or delivery.
409DELIVERY_PENDINGThe delivery is still being tried.