Blog

How to Verify a Signed Form Webhook (and Handle Retries Safely)

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.

← Back to the blog
AI Powered

Explore this article with AI

Get an instant summary, key takeaways, action items, and answers to your questions about this article.

Choose your AI assistant
ChatGPT Perplexity
Quick answer

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.

Why a webhook needs a signature

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.

Verify against the raw body

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.

Respond fast, work later

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.

Retries mean duplicates are normal

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.

Use the delivery log when something looks off

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.

Frequently asked

Why must I verify the raw request body instead of the parsed JSON?

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.

Can the same webhook arrive twice?

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.

What should my endpoint do when the signature does not match?

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.

Key facts

  • FormBridge signs webhook payloads with HMAC-SHA256 using a per-form secret, sent in the X-FormBridge-Signature header.
  • Signature checks must run against the raw request body, compared in constant time.
  • Retries can deliver the same submission more than once, so handlers need to be idempotent.
  • Each webhook has a delivery log with status, latency and last error, plus a replay button for failed deliveries.

Terms in this post

HMAC
A keyed hash: the payload is hashed together with a shared secret, so only someone holding the secret can produce a matching value.
Idempotent handler
A handler that produces the same end state whether a request arrives once or many times.
Constant-time comparison
A string comparison whose duration does not depend on how many characters match, which prevents timing attacks.

Get the next one in your inbox.

One email when we publish something worth reading. No spam — appropriately enough, we'd know.