Backups & Automation

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.

Last updated

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

EventWhen it is sent
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 or rollback of an app went live.
deployment.failedA deployment or rollback of an app 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 sends a webhook.test event.

Formats

FormatBody
JSON (signed)The event as JSON, signed with HMAC-SHA256 in X-VaultPanel-Signature.
SlackA message for a Slack incoming webhook: { "text": "VaultPanel: ..." }.
DiscordA 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

FieldWhat it does
NameHow it is listed, such as Ops channel.
FormatJSON (signed), Slack or Discord.
URLWhere requests go: an http or https URL, without user:password@. Kept encrypted; lists show only its host.
EventsAt least one event.
OnUntick 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:

HeaderValue
Content-Typeapplication/json
User-AgentVaultPanel-Webhook/1
X-VaultPanel-EventThe event, such as deployment.succeeded.
X-VaultPanel-DeliveryThe delivery's id. It stays the same when a delivery is retried.
X-VaultPanel-TimestampUnix time in seconds when this attempt was sent.
X-VaultPanel-SignatureJSON 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:

deployment.succeeded
{
  "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

Eventdata fields
backup.succeeded, backup.failedbackup (id, trigger, sizeBytes), resource (type, name), server (id, name), and error (code, message) when it failed.
restore.succeeded, restore.failedAs for backups, plus restore (id, safetyBackupId).
cron.failedcronJob (id, name, user, owner), run (status, exitCode, trigger, startedAt, durationMs, outputTail: the last 1,000 characters of output), server.
deployment.succeeded, deployment.failedapplication (id, name), kind (deploy or rollback), commit, releaseId, server, and error when it failed.
alert.firingserver, rule (the rule's name), severity, subject, message.
alert.resolvedserver, rule, subject.
server.offlineserver, lastSeenAt.
server.onlineserver.
ssl.expiring, ssl.expiredwebsite (id, name), server, domains, notAfter, daysLeft, staging.
ssl.renew_failedwebsite, server, domains, notAfter, error.
webhook.testwebhook (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.

server.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);
server.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);
vaultpanel-webhook.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.

AddressesAllowed
Public addressesAlways.
Private ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, IPv6 unique localOnly with VAULTPANEL_WEBHOOK_ALLOW_PRIVATE=true in the panel's .env.
Loopback, link-local (including cloud metadata at 169.254.169.254), multicastNever.

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.