Get the next one in your inbox.
One email when we publish something worth reading. No spam — appropriately enough, we'd know.
A signed webhook proves a request really came from your form backend. Here's how to verify the signature on the raw body, respond fast, and stay safe when deliveries are retried.

Get an instant summary, key takeaways, action items, and answers to your questions about this article.
Verify the signature against the raw request body, not re-serialized JSON, and compare it in constant time. Return a 2xx quickly, do the heavy work afterward, and make your handler idempotent — retries mean the same submission can legitimately arrive more than once.
A webhook URL is just a public endpoint. Anyone who finds it can POST to it, and without a check your system will happily treat a forged request as a real lead. Signing fixes that — but only if the receiving side verifies it correctly, and handles the retries that make webhooks reliable in the first place.
When a form submission is forwarded to your own URL, your server has no built-in way to know who sent the request. A signature closes that gap: the sender computes a keyed hash of the payload using a secret only the two of you know, and sends it in a header. If your server can reproduce the same hash, the request is authentic and unmodified.
FormBridge signs webhook payloads with HMAC-SHA256 using a per-form secret, and sends the result in the X-FormBridge-Signature header. Because the secret is per form, a leak on one form never exposes the others.
The most common mistake is verifying a re-serialized object. Parse the JSON first and stringify it again, and key order, whitespace or number formatting can differ from what was signed — so a perfectly valid request fails, or worse, you loosen the check until it passes everything. Capture the raw bytes of the request body before any parsing and hash those.
import crypto from 'node:crypto';
// rawBody: the unparsed request body (Buffer or string)
const expected = crypto
.createHmac('sha256', process.env.FORMBRIDGE_WEBHOOK_SECRET)
.update(rawBody)
.digest('hex');
const received = req.headers['x-formbridge-signature'] || '';
const ok =
expected.length === received.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
if (!ok) return res.status(401).end();
Two details matter here. Compare with timingSafeEqual rather than ===, so response timing can't leak how many leading characters matched. And check the digest encoding shown in your form's webhook settings before you ship, so you compare like with like.
Treat the webhook request as a delivery receipt, not a job. Verify, enqueue whatever needs to happen — CRM write, Slack message, database insert — and return a 2xx straight away. If your handler runs a slow downstream call inline and times out, the sender sees a failure and will try again, and you've created your own duplicate.
Reliable delivery and exactly-once delivery are different promises. FormBridge retries failed deliveries with backoff, so a short outage on your side doesn't lose a lead — but it also means the same submission can reach you more than once. Make the handler idempotent: store the submission's identifier the first time you process it, and skip anything you've already seen.
2xx for duplicates too — telling the sender "already handled" stops further retries.Each webhook has a delivery dashboard showing status, latency and the last error, with a replay button for any failed delivery. When a handler bug has been fixed, replaying the failed deliveries is faster and safer than asking anyone to resubmit a form. If you route submissions by field value, the payload also carries a routing.matched_rule field, so downstream code can filter without re-implementing the rules — see conditional routing.
For the full list of destinations a submission can reach, see the integrations page.
Because the signature was computed over the exact bytes that were sent. Parsing and re-serializing can change key order, whitespace or number formatting, so the hash you compute will not match even for a genuine request.
Yes. Failed deliveries are retried so that a short outage does not lose a submission, which means a handler can see the same submission more than once. Dedupe on the submission ID and return a 2xx for ones you have already processed.
Reject the request with a 401 and do no further work. Do not log the secret, and do not fall back to accepting unsigned requests — that defeats the point of signing.
One email when we publish something worth reading. No spam — appropriately enough, we'd know.