Webhooks
API reference for outgoing webhooks - creating JSON, Slack and Discord webhooks, rotating signing secrets, sending tests and reading or redelivering deliveries.
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.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/webhooks | List webhooks |
| POST | /api/v1/webhooks | Create a webhook |
| GET | /api/v1/webhooks/:id | Get a webhook |
| PATCH | /api/v1/webhooks/:id | Update a webhook |
| DELETE | /api/v1/webhooks/:id | Delete a webhook |
| POST | /api/v1/webhooks/:id/test | Send a test |
| GET | /api/v1/webhooks/:id/deliveries | List deliveries |
| POST | /api/v1/webhooks/:id/deliveries/:deliveryId/redeliver | Redeliver |
Events
| Event | When |
|---|---|
backup.succeeded | A backup finished. |
backup.failed | A backup failed. |
restore.succeeded | A restore finished. |
restore.failed | A restore failed. |
cron.failed | A cron job failed or timed out. |
deployment.succeeded | A deployment went live. |
deployment.failed | A deployment failed. |
alert.firing | An alert started firing. |
alert.resolved | An alert resolved. |
server.offline | A server went offline. |
server.online | A server came back online. |
ssl.expiring | An SSL certificate is close to expiring. |
ssl.expired | An SSL certificate expired. |
ssl.renew_failed | Automatic SSL renewal failed. |
Test deliveries use the event webhook.test.
The webhook object
| Field | Type | Description |
|---|---|---|
id, name | string | The webhook. |
host | string | Where it sends, such as https://hooks.slack.com. Lists never include the full URL: chat webhook URLs are secrets. |
url | string | Only in Get a webhook. |
format | string | json (signed), slack or discord. |
events | string[] | The events it receives. |
enabled | boolean | Paused when false. |
lastDelivery | object or null | { at, status }. |
createdAt, updatedAt | string | Timestamps. |
List webhooks
/api/v1/webhooksReturns your webhooks a page at a time, without plugin webhooks.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
sort, order | string | No | name (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
/api/v1/webhooksCreates 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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Up to 100 characters. |
url | string | Yes | A full http or https URL, up to 2000 characters, without user:password@. |
format | string | No | json (default), slack or discord. |
events | string[] | Yes | At least one event. |
enabled | boolean | No | Default 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
| Status | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | Not a full http or https URL, credentials in the URL, no events, or an unknown event. |
Get a webhook
/api/v1/webhooks/:idReturns 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No webhook with this id. |
| 409 | PLUGIN_WEBHOOK | It carries a plugin's events: manage it on the plugin. |
Update a webhook
/api/v1/webhooks/:idChanges 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No webhook with this id. |
| 409 | PLUGIN_WEBHOOK | It carries a plugin's events. |
| 422 | VALIDATION_ERROR | Nothing to update, or an invalid field. |
Delete a webhook
/api/v1/webhooks/:idDeletes 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
/api/v1/webhooks/:id/testSends 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
/api/v1/webhooks/:id/deliveriesReturns the webhook's deliveries, newest first, with their payloads and outcomes. Deliveries are kept for 30 days.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | pending (still being tried), succeeded or failed. |
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
order | string | No | desc (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
/api/v1/webhooks/:id/deliveries/:deliveryId/redeliverSends 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such webhook or delivery. |
| 409 | DELIVERY_PENDING | The delivery is still being tried. |
Cron jobs
API reference for cron jobs that run as a website's or app's own Linux user - creating, changing, running now and reading their run history.
AI assistant
API reference for the AI assistant - provider settings, the free model on the panel's server, conversations, and approving the changes it proposes.