# Webhook notifications

URL: https://docs.vaultpanel.net/guides/backups-and-automation/webhooks

> Send signed JSON, Slack or Discord notifications when backups or cron jobs fail, deployments finish, alerts fire, servers go offline or certificates expire.

Webhooks tell other systems when something happens in the panel: a chat channel, an incident tool or
your own script. VaultPanel sends a `POST` request for each event a webhook subscribes to, signs JSON
requests with the webhook's secret, and retries failed deliveries.

## Events

| Event | When it is sent |
| --- | --- |
| `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 or rollback of an app went live. |
| `deployment.failed` | A deployment or rollback of an app 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** sends a `webhook.test` event.

## Formats

| Format | Body |
| --- | --- |
| **JSON (signed)** | The event as JSON, signed with HMAC-SHA256 in `X-VaultPanel-Signature`. |
| **Slack** | A message for a Slack incoming webhook: `{ "text": "VaultPanel: ..." }`. |
| **Discord** | A message for a Discord channel webhook: `{ "content": "VaultPanel: ...", "allowed_mentions": { "parse": [] } }`, cut to 2,000 characters. |

Slack and Discord messages are one line that summarizes the event, such as
`VaultPanel: Backup of database shop on web-1 failed: ...`.

## Add a webhook

### Open Webhooks

Go to **Webhooks** under **Automation** and click **Add webhook**. Managing webhooks needs the
`webhooks.manage` permission (owners and admins).

### Fill it in

| Field | What it does |
| --- | --- |
| **Name** | How it is listed, such as `Ops channel`. |
| **Format** | **JSON (signed)**, **Slack** or **Discord**. |
| **URL** | Where requests go: an `http` or `https` URL, without `user:password@`. Kept encrypted; lists show only its host. |
| **Events** | At least one event. |
| **On** | Untick to stop sending without deleting the webhook. |

For Slack, create an incoming webhook in Slack and paste its URL. For Discord, create a webhook in
the channel's **Integrations** settings.

### Copy the signing secret

For JSON webhooks, the signing secret (it starts with `whsec_`) is shown once. Store it where your
receiver can read it. **Replace signing secret** makes a new one.

### Send a test

Click **Test**. The panel sends a `webhook.test` event straight away and shows the HTTP status your
endpoint answered.

## The request

Every delivery is a `POST` with these headers:

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |
| `User-Agent` | `VaultPanel-Webhook/1` |
| `X-VaultPanel-Event` | The event, such as `deployment.succeeded`. |
| `X-VaultPanel-Delivery` | The delivery's id. It stays the same when a delivery is retried. |
| `X-VaultPanel-Timestamp` | Unix time in seconds when this attempt was sent. |
| `X-VaultPanel-Signature` | JSON format only: `sha256=` followed by the hex HMAC-SHA256 of the timestamp, a `.`, and the body. |

A JSON body has the event, when it happened, its data and the delivery id:

```json
{
  "event": "deployment.succeeded",
  "occurredAt": "2026-11-10T09:31:02.118Z",
  "data": {
    "application": { "id": "0b9f6c1e-3f0e-4c63-9a52-2f7c2d0f4a11", "name": "shop-api" },
    "kind": "deploy",
    "commit": "8c1d2e4f9a7b3c5d6e1f2a3b4c5d6e7f8a9b0c1d",
    "releaseId": "20261110093015-a1b2c3",
    "server": { "id": "5d2a7e90-1c3b-4f6d-8e9a-0b1c2d3e4f50", "name": "web-1" }
  },
  "id": "e3b4c5d6-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
}
```

### Event data

| Event | `data` fields |
| --- | --- |
| `backup.succeeded`, `backup.failed` | `backup` (`id`, `trigger`, `sizeBytes`), `resource` (`type`, `name`), `server` (`id`, `name`), and `error` (`code`, `message`) when it failed. |
| `restore.succeeded`, `restore.failed` | As for backups, plus `restore` (`id`, `safetyBackupId`). |
| `cron.failed` | `cronJob` (`id`, `name`, `user`, `owner`), `run` (`status`, `exitCode`, `trigger`, `startedAt`, `durationMs`, `outputTail`: the last 1,000 characters of output), `server`. |
| `deployment.succeeded`, `deployment.failed` | `application` (`id`, `name`), `kind` (`deploy` or `rollback`), `commit`, `releaseId`, `server`, and `error` when it failed. |
| `alert.firing` | `server`, `rule` (the rule's name), `severity`, `subject`, `message`. |
| `alert.resolved` | `server`, `rule`, `subject`. |
| `server.offline` | `server`, `lastSeenAt`. |
| `server.online` | `server`. |
| `ssl.expiring`, `ssl.expired` | `website` (`id`, `name`), `server`, `domains`, `notAfter`, `daysLeft`, `staging`. |
| `ssl.renew_failed` | `website`, `server`, `domains`, `notAfter`, `error`. |
| `webhook.test` | `webhook` (`id`, `name`), `message`. |

## Verify the signature

Check the signature of every JSON request before you trust it. Compute the HMAC over the raw body,
exactly as received, before parsing it. Rejecting timestamps older than a few minutes also stops
replayed requests.

**Node.js**

```js
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const secret = process.env.VAULTPANEL_WEBHOOK_SECRET; // whsec_...

app.post('/vaultpanel', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-VaultPanel-Timestamp') ?? '';
  const signature = req.get('X-VaultPanel-Signature') ?? '';
  const expected = `sha256=${crypto.createHmac('sha256', secret).update(`${timestamp}.${req.body}`).digest('hex')}`;

  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)) &&
    Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  if (!valid) return res.sendStatus(401);

  const { event, data } = JSON.parse(req.body);
  console.log(event, data);
  res.sendStatus(204);
});

app.listen(3000);
```

**SDK**

```js
import { verifyEvent } from '@vaultpanel/sdk';

// rawBody: the request body exactly as received (a string or Buffer).
const event = verifyEvent({ body: rawBody, headers: req.headers, secret: process.env.VAULTPANEL_WEBHOOK_SECRET });
if (!event) {
  // Wrong signature, or a timestamp more than 5 minutes off.
  return res.writeHead(401).end();
}
console.log(event.event, event.data);
```

**PHP**

```php
<?php
$secret = getenv('VAULTPANEL_WEBHOOK_SECRET'); // whsec_...
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_VAULTPANEL_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_VAULTPANEL_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $signature) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
error_log($event['event']);
http_response_code(204);
```

## Deliveries and retries

The panel's worker sends deliveries in the background, so the `vaultpanel-worker` service must be
running. A delivery succeeds when your endpoint answers with a `2xx` status within 10 seconds.

A delivery that fails with a network error, a timeout, or a `408`, `429` or `5xx` answer is tried
again up to 3 more times: 1 minute, 5 minutes and 30 minutes after the previous attempt. Any other
answer, or an address webhooks may not reach, fails it straight away. Deliveries still pending for a
webhook that was turned off fail.

Open a webhook's deliveries to see each one's event, status, HTTP status, duration and error.
**Send again** resends a finished delivery. Deliveries are kept for 30 days.

## Private addresses

Webhooks only go to public addresses by default. VaultPanel checks the address after DNS resolution
and connects to that same address, so a name cannot resolve to something else later.

| Addresses | Allowed |
| --- | --- |
| Public addresses | Always. |
| Private ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, IPv6 unique local | Only with `VAULTPANEL_WEBHOOK_ALLOW_PRIVATE=true` in the panel's `.env`. |
| Loopback, link-local (including cloud metadata at `169.254.169.254`), multicast | Never. |

New panels refuse private addresses since version 0.2.0. Panels installed earlier keep their previous
behaviour.

## Plugins

A plugin receives its events through a webhook of its own, managed on the plugin's page under
**Plugins** rather than on **Webhooks**. See [Plugins](https://docs.vaultpanel.net/developers/plugins).
