Skip to main content
This page describes the fields you set when you register a webhook in the dashboard (Settings > Webhooks > Add webhook +).

​
Endpoint URL

The URL that receives notifications. It must be a public https URL with a valid TLS certificate that is not self-signed. Bodyguard denies webhooks registered with an http URL.

​
Events

A webhook is triggered by one or more events that you subscribe to: One webhook can subscribe to several events. You can also add another webhook with a different URL to handle other events separately.
Bodyguard also sends a webhook.validate event, which you cannot subscribe to. Your endpoint must answer it with a 2xx status code when you create the webhook or change its URL.
For the content of each event, see Payloads.

​
Signing secret

Bodyguard generates a signing secret for each webhook. It starts with whsec_ followed by a base64-encoded value. The dashboard displays it only once, when you create the webhook, so copy it then. See Connect your webhook. Bodyguard uses it to sign every request, and you use it to verify that a request comes from Bodyguard and was not altered. See Quick start.
Treat the signing secret like a password. Store it in a secrets manager or an environment variable, and never expose it in client-side code.

​
Contacts

Each new webhook requires at least one contact. Bodyguard sends alerts to every contact if it encounters issues reaching your endpoint, such as the emails described in Handling errors. Each contact must be a user registered to your organization on the dashboard.

​
Webhook statuses

Each webhook has a status that describes its current state: The ERROR status is set automatically. While a webhook is DISABLED or ERROR, Bodyguard doesn’t send its events, and they can’t be replayed when you enable the webhook again. To enable a webhook in error, fix the issue, then enable it manually from the dashboard. See Handling errors.

​
Next steps

Payloads

Headers, payload structure, and an example for each event type.