Prerequisites
- The signing secret of your webhook. It starts with
whsec_. See Configuration. - A server that can expose a public HTTPS endpoint.
- The endpoint must complete a valid TLS handshake, with a certificate from a trusted certificate authority. Self-signed certificates are not accepted.
- The endpoint must answer within 10 seconds. Otherwise, the delivery is considered a failure.
How signing works
Bodyguard signs each request as described in the Verifying webhook authenticity section of the Standard Webhooks specification. Bodyguard uses the symmetric signature scheme:HMAC-SHA256 with your whsec_ signing secret, and the v1 signature identifier.
Create your endpoint
Install the library for your language:POST requests and verifies each one. Pass the signing secret in the BODYGUARD_WEBHOOK_SECRET environment variable. For the content of event.data, see Payloads › Event types.
webhook.validate event does not need special handling: it is signed like any other event, so your endpoint verifies it and answers with a 2xx status code.
Run your endpoint:
Other languages
Standard Webhooks also provides libraries for Java and Kotlin, Rust, Ruby, PHP, C#, and Elixir. See the list of libraries.Verify a signature without a library
Verify a signature without a library
If no library fits your stack, implement the verification described in the Standard Webhooks specification:
- Read the
webhook-id,webhook-timestamp, andwebhook-signatureheaders. - Reject the request if
webhook-timestampis too far from the current time (the official libraries use five minutes). - Build the signed content:
{webhook-id}.{webhook-timestamp}.{raw body}. - Remove the
whsec_prefix from your signing secret and base64-decode the rest. Compute the HMAC SHA256 of the signed content with this key, and base64-encode the result. - Compare it, in constant time, with each
v1,signature in thewebhook-signatureheader. The request is valid if one of them matches.
Test your endpoint
When you register the webhook or change its URL, Bodyguard sends awebhook.validate event: if your endpoint doesn’t answer with a 2xx status code, the registration fails. To check your endpoint at any time, click Send test event in the dashboard.
Process events safely
- Answer quickly. Return a
2xxstatus code within 10 seconds, as soon as you have verified and stored the event, and do the heavy work afterwards. Any other response, or no response, is a failure and triggers a retry. - Deduplicate with
webhook-id. Bodyguard retries failed deliveries with the samewebhook-idheader. Store the identifiers you have processed, and skip the ones you have already seen. - Keep the secret private. Load it from the environment, and never log it.
Next steps
Configuration
Events, signing secret, contacts, and webhook statuses.