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 enable the webhook, or change the URL or the custom headers of an enabled webhook, Bodyguard sends awebhook.validate event: if your endpoint doesn’t answer with a 2xx status code, the change 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, custom headers, contacts, and webhook statuses.