# Webhooks

Webhooks are managed as Notification Channels in SimpleBackups.

You can create and share Notification Channels across your team and backups, then enable them individually on the backups you want and for the events you need.

# How webhooks work

SimpleBackups webhooks work by firing a POST request to the endpoint you set. Relevant data to the backp event will be set in the POST payload.

# Creating a webhook

  • Go to your backups page and click "Add Notification Channel" from the "Notifications" tab. Custom backup schedule
  • Select the channel "Webhook", give it a name and paste the URL you want us to post to. Custom backup schedule
  • Finally, select the events you want the webhook to be triggered for.

# Webhook validation

All the webhooks sent are signed by a signing secret, unique to your team/organization. You can find the signing secret once you create a webhook. While you are not required to validate the incoming webhooks, it is generally recommended to do so.

# Successful event example payload

{
    "id": **RUN_ID**,
    "type": "backup",
    "status": "success",
    "started_at": "2021-12-12 12:12:12",
    "finished_at": "2021-12-12 12:21:12",
    "backup": {
        "id": **BACKUP_ID**,
        "name": "Acme Project",
        "type": "file"
    },
    "server": {
        "id": **SERVER_ID**,
        "name": "Acme Server"
    },
    "storage": {
        "id": **STORAGE_ID**,
        "name": "Acme Storage"
    }
}

# Failure event example payload

{
    "id": **RUN_ID**,
    "type": "backup",
    "status": "error",
    "started_at": "2021-10-10 10:01:10",
    "finished_at": "2021-10-10 10:10:10",
    "backup": {
        "id": **BACKUP_ID**,
        "name": "Acme Project",
        "type": "file"
    },
    "server": {
        "id": **SERVER_ID**,
        "name": "Acme Server"
    },
    "storage": {
        "id": **STORAGE_ID**,
        "name": "Acme Storage"
    }
}

# Webhook signature verification

An HTTP header called SB-Signature is included in every webhook SimpleBackups sends. That header is the hash of the payload sent.

To validate the signature and confirm that it is authentic, you can follow this example (given in PHP, feel free to use any other language):

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

Where:

$jsonPayload is the JSON body of the POST request

$secret is the signing secret shown on your SimpleBackups account once you create a webhook

You should validate that the $signature you just computed is identical to the SB-Signature header in the webhook request you received.

Last Updated: 3/9/2022, 11:55:08 PM