Skip to main content
A webhook notifies your endpoint when events occur in Bodyguard, such as a message or an author being updated. This page walks you through registering one in the dashboard. To learn how webhooks work, see the Webhooks introduction.

​
Prerequisites

You need a public HTTPS endpoint that is ready to receive notifications. Bodyguard denies webhooks registered with an http URL. See the Quick start to build your endpoint and verify the signature of each request.

​
Steps

1

Add a webhook

  1. Click the gear icon in the left menu to open Settings, select Webhooks, then click Add webhook.
    Webhooks page with the Settings gear icon (1), the Webhooks entry (2), and the Add webhook button (3) highlighted

    Settings > Webhooks

  2. Fill in the form. The numbers match the screenshot below. 1. Enter the Endpoint URL that receives notifications. It must be publicly reachable over HTTPS.
    2. Add at least one Alert contact. Bodyguard notifies your contacts when deliveries to this endpoint fail. Each contact must be a user registered to your organization on the dashboard.
    3. Choose the Sources the webhook applies to. In this example, All the organization’s API sources is selected.
    4. Select the Events you subscribe to: message.updated (when a message is updated by Bodyguard) and author.updated (when an author is updated by Bodyguard).
    5. Click Create webhook.
    New webhook dialog with the Endpoint URL (1), Alert contact (2), Sources (3), and Events (4) fields and the Create webhook button (5) highlighted

    New webhook form

    See Configuration for each field and Payloads for the content of each event.
    When you create the webhook, Bodyguard sends a webhook.validate event to your endpoint. Your endpoint must answer it with a 2xx status code.
2

Copy your signing secret

Bodyguard generates a signing secret when you create the webhook and displays it in the Webhook created dialog. Copy it with the copy icon and store it somewhere safe, then click Done. The secret starts with whsec_.
Webhook created dialog with the signing secret field and its copy icon highlighted

Signing secret displayed at creation

The signing secret is shown only once. You can’t see it again after closing the dialog. Treat it like a password and never expose it in client-side code.
You use the signing secret to verify that each request comes from Bodyguard. See the Quick start.
3

Enable and test your webhook

Your webhook is created with the Disabled status. Enable it once your endpoint is ready to receive events. Click the ⋮ menu at the end of the webhook row to open its actions:
Webhooks list with the three-dot button of the webhook row (1) and its actions menu highlighted, showing Send test event, Edit webhook, Enable webhook, and Delete webhook

Webhook actions menu

  • Enable webhook activates the webhook.
  • Send test event lets you check that your endpoint receives events.
  • Edit webhook and Delete webhook let you change or remove the webhook.
While a webhook is disabled, Bodyguard doesn’t send its events, and they can’t be replayed when you enable the webhook again. See Webhook statuses.

​
Next steps

Quick start

Build an endpoint and verify each request with a Standard Webhooks library.

Configuration

Events, signing secret, contacts, and webhook statuses.

Handling errors

What happens when your endpoint fails, and how to recover.