Backup Webhook

Integrate your backups with other processes and systems.

Webhooks are one of the notification channel types. You create a webhook channel once, share it across your Team, then enable it on the backups and events you need.

How webhooks work

SimpleBackups sends an HTTP POST request with a JSON body to the endpoint you configure, every time a subscribed event fires.

Creating a webhook

1. Open a backup and go to the Notifications tab
2. Click Add Notification Channel
3. Select Webhook, give it a name, and paste the URL you want us to POST to
4. Save, then tick the events you want it fired for in the notifications grid

Available events

Event	Fires when
backup-success	A backup run completes successfully
backup-error	A backup run fails
snapshot-success	A snapshot completes successfully
snapshot-error	A snapshot fails
stack-discovery-new-resources	Stack discovery finds new resources

Payload

The payload is the same shape for success and failure — only status differs.

{
  "id": 123456,
  "type": "backup",
  "status": "success",
  "started_at": "2026-07-29 12:12:12",
  "finished_at": "2026-07-29 12:21:12",
  "backup": {
    "id": 4321,
    "name": "Acme Project",
    "type": "file"
  },
  "server": {
    "id": 87,
    "name": "Acme Server"
  },
  "storage": {
    "id": 12,
    "name": "Acme Storage"
  }
}

A failure delivers the same fields with "status": "error":

{
  "id": 123457,
  "type": "backup",
  "status": "error",
  "started_at": "2026-07-29 10:01:10",
  "finished_at": "2026-07-29 10:10:10",
  "backup": {
    "id": 4321,
    "name": "Acme Project",
    "type": "file"
  },
  "server": {
    "id": 87,
    "name": "Acme Server"
  },
  "storage": {
    "id": 12,
    "name": "Acme Storage"
  }
}

Field notes:

• id is the run (log) ID, not the backup ID — use backup.id to identify the backup.
• Timestamps are YYYY-MM-DD HH:MM:SS in UTC. They are not ISO 8601, so parse accordingly.
• The payload carries no error message, file size, or duration. Fetch those from the API using the run ID if you need them.
• A backup locked by a plan limit sends "status": "locked" with a locked_features array in place of id, on the backup-error event.

Response codes and retries

Return a status code in the 2xx range to acknowledge the delivery.

• Any other code counts as a failure and is retried up to 3 times.
• Exception: 400, 401, 403, and 404 are treated as permanent. They are not retried — a misconfigured or removed endpoint gets exactly one attempt.

!Retries are immediate

Retries happen back to back with no backoff delay. If your endpoint is rate-limited or slow to warm up, return a 2xx quickly and process the payload asynchronously rather than relying on the retries.

Verifying the signature

Every webhook includes an SB-Signature header — an HMAC-SHA256 hash of the exact request body, keyed with a signing secret unique to your Team. The secret is shown when you create the webhook channel.

Validating is optional but recommended: it is what proves a request actually came from SimpleBackups.

$signature = hash_hmac('sha256', $jsonPayload, $secret);

Where:

• $jsonPayload is the raw JSON body of the POST request — hash it before parsing, since re-serialising can change the bytes and break the comparison
• $secret is the signing secret from your webhook channel

Compare your computed $signature against the SB-Signature header. Use a constant-time comparison (hash_equals in PHP) rather than ==.

SSecurity

The signing secret is shared across every webhook channel in your Team. Treat it as a credential, and rotate it with us if you believe it has been exposed.

NotificationsAll notification channel types, and how to pick which events fire.›Backup automationTrigger and query backups from your own systems with the API.›