Skip to main content
Bodyguard signs every webhook request, so you can check that it comes from Bodyguard and that nobody altered it. Signatures follow the Standard Webhooks specification, so you verify them with the official open-source libraries instead of writing the cryptography yourself.

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:
Then create an endpoint that accepts 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.
Verify the raw request body, exactly as received. If a framework parses the JSON and you serialize it again, whitespace and key order can change and the signature check fails.
The 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.
If no library fits your stack, implement the verification described in the Standard Webhooks specification:
  1. Read the webhook-id, webhook-timestamp, and webhook-signature headers.
  2. Reject the request if webhook-timestamp is too far from the current time (the official libraries use five minutes).
  3. Build the signed content: {webhook-id}.{webhook-timestamp}.{raw body}.
  4. 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.
  5. Compare it, in constant time, with each v1, signature in the webhook-signature header. The request is valid if one of them matches.

Test your endpoint

When you register the webhook or change its URL, Bodyguard sends a webhook.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 2xx status 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 same webhook-id header. 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.