Skip to main content
Anyone who knows your webhook URL could send it a fake message. To protect you, we sign every webhook with your endpoint’s secret. You check the signature, and ignore any message where it doesn’t match.

How the signature works

  1. We take the raw request body, exactly as sent.
  2. We create an HMAC-SHA256 of it using your endpoint’s signing secret.
  3. We put the result, as lowercase hex, in the X-Webhook-Signature header.
You do the same calculation and compare.
Use the raw body, before your framework turns it into JSON. If the body is parsed and re-encoded, even a changed space breaks the signature.

Code examples

Get your signing secret from the Bridge app: open your endpoint under Webhooks.
Compare signatures with a constant-time function, as in the examples above (timingSafeEqual, compare_digest, hash_equals). A normal == comparison can leak information to an attacker.

If the signature doesn’t match

  • Check you’re using the secret for this endpoint, and for the right environment (sandbox or live).
  • Check you’re using the raw body.
  • If you recently reset the secret, update your server with the new one.
Reply with 401 and don’t process the message.
Last modified on October 29, 2026