Webhook notifications
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:
{
"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.
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);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
$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.
Running cron jobs
Run commands on a schedule as a website's or app's own Linux user, in the server's time zone, with the output of every run kept in the panel.
Security
How VaultPanel protects the panel and your servers, and where to manage firewalls, SSH, brute-force protection, updates, sign-in and access.