# Webhooks

URL: https://docs.vaultpanel.net/api-reference/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](https://docs.vaultpanel.net/guides/backups-and-automation/webhooks). Webhooks that carry a plugin's events are managed on the plugin instead; see [Plugins](https://docs.vaultpanel.net/api-reference/plugins).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/webhooks` | [List webhooks](https://docs.vaultpanel.net/api-reference/webhooks#list-webhooks) |
| POST | `/api/v1/webhooks` | [Create a webhook](https://docs.vaultpanel.net/api-reference/webhooks#create-a-webhook) |
| GET | `/api/v1/webhooks/:id` | [Get a webhook](https://docs.vaultpanel.net/api-reference/webhooks#get-a-webhook) |
| PATCH | `/api/v1/webhooks/:id` | [Update a webhook](https://docs.vaultpanel.net/api-reference/webhooks#update-a-webhook) |
| DELETE | `/api/v1/webhooks/:id` | [Delete a webhook](https://docs.vaultpanel.net/api-reference/webhooks#delete-a-webhook) |
| POST | `/api/v1/webhooks/:id/test` | [Send a test](https://docs.vaultpanel.net/api-reference/webhooks#send-a-test) |
| GET | `/api/v1/webhooks/:id/deliveries` | [List deliveries](https://docs.vaultpanel.net/api-reference/webhooks#list-deliveries) |
| POST | `/api/v1/webhooks/:id/deliveries/:deliveryId/redeliver` | [Redeliver](https://docs.vaultpanel.net/api-reference/webhooks#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](https://docs.vaultpanel.net/api-reference/webhooks#get-a-webhook). |
| `format` | string | `json` (signed), `slack` or `discord`. |
| `events` | string[] | The [events](https://docs.vaultpanel.net/api-reference/webhooks#events) it receives. |
| `enabled` | boolean | Paused when `false`. |
| `lastDelivery` | object or null | `{ at, status }`. |
| `createdAt`, `updatedAt` | string | Timestamps. |

## List webhooks

`GET /api/v1/webhooks` — Permission: webhooks.manage — Token scope: manage

Returns 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**

```bash
curl https://panel.example.com/api/v1/webhooks \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.webhooks.list();
```

**Response** `200 OK`

```json
{
  "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` — 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**

| 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](https://docs.vaultpanel.net/api-reference/webhooks#events). |
| `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**

```bash
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"]
  }'
```

**JavaScript**

```js
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`

```json
{
  "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

`GET /api/v1/webhooks/:id` — Permission: webhooks.manage — Token scope: manage

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

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const webhook = await panel.webhooks.get(webhookId);
```

**Response** `200 OK`: the [webhook object](https://docs.vaultpanel.net/api-reference/webhooks#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

`PATCH /api/v1/webhooks/:id` — 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**

```bash
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 }'
```

**JavaScript**

```js
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

`DELETE /api/v1/webhooks/:id` — Permission: webhooks.manage — Token scope: manage

Deletes the webhook.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.webhooks.remove(webhookId);
```

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

## Send a test

`POST /api/v1/webhooks/:id/test` — 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**

```bash
curl https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a/test \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { delivery } = await panel.webhooks.test(webhookId);
console.log(delivery.status, delivery.responseStatus);
```

**Response** `200 OK`

```json
{
  "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` — 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**

| 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**

```bash
curl "https://panel.example.com/api/v1/webhooks/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a/deliveries?status=failed" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.webhooks.deliveries(webhookId, { status: 'failed' });
```

**Response** `200 OK`: `{ items, pagination }` of deliveries, as in [Send a test](https://docs.vaultpanel.net/api-reference/webhooks#send-a-test).

## Redeliver

`POST /api/v1/webhooks/:id/deliveries/:deliveryId/redeliver` — Permission: webhooks.manage — Token scope: manage

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

**Example request**

**cURL**

```bash
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"
```

**JavaScript**

```js
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. |
