How to verify webhook signatures in Node.js
A webhook URL is public, so anyone can post fake events to it. Learn how HMAC signatures, timing-safe comparison and timestamps keep a receiver safe.
You have set up a webhook so your server is told about every new form submission. The URL it posts to is reachable from the whole internet, which means anyone who finds or guesses it can send your server a made-up submission.
Signature verification is how the receiver tells real deliveries from forged ones. This guide explains the idea, then builds a complete Node.js receiver for FormDB webhooks.
What webhook signing is
A webhook is an HTTP request that one service sends to another when something happens. In FormDB's case, a POST request with the submission as JSON is sent to a URL you choose each time a form receives a submission.
Signing adds proof of who sent it. The sender and receiver share a secret string. For each delivery, the sender runs the request body and the secret through a function called HMAC (hash-based message authentication code) and puts the result in a header. HMAC with SHA-256 produces a fixed-length fingerprint that depends on every byte of the message and on the secret.
The receiver does the same calculation with its copy of the secret. If the two results match, two things are true:
- The request came from someone who knows the secret.
- The body was not changed on the way.
Someone without the secret cannot produce a valid signature, even if they have seen earlier deliveries.
Why you should verify every webhook
Without verification, your webhook handler trusts any request that reaches it. Depending on what the handler does, a forged request could add fake leads to your customer database, trigger emails, or start whatever process you attached to a new submission.
Keeping the URL secret is not enough. URLs end up in logs, proxies and configuration files. A signature check costs a few lines of code and removes the risk.
How FormDB signs webhook requests
When you add a webhook to a form, FormDB generates a signing secret that starts with whsec_. You can view it, and rotate it, in the form's Integrations tab. Each delivery looks like this:
POST /webhooks/formdb HTTP/1.1
Content-Type: application/json
User-Agent: FormDB-Webhooks/1.0
X-FormDB-Event: submission.created
X-FormDB-Delivery: <delivery id>
X-FormDB-Signature: t=1795000000,v1=5f2b...c41eThe X-FormDB-Signature header has two parts separated by a comma:
tis the time the request was sent, as a Unix timestamp in seconds.v1is the signature, written as lower-case hexadecimal.
The signature is computed like this:
v1 = HMAC-SHA256(key = signing secret, message = t + "." + raw request body)Two details are worth getting right:
- The key is the whole secret string, including the
whsec_prefix, used as plain text. Do not strip the prefix or base64-decode it. - The message uses the raw body, the exact bytes that arrived, before any JSON parsing.
Use the raw body, not parsed JSON
This is the most common reason verification fails. Web frameworks usually parse a JSON body into an object for you. If you turn that object back into text with JSON.stringify, the spacing or key order may differ from what was sent, and a single different byte gives a completely different HMAC.
Capture the body as bytes first, verify, and only then parse it. In Express that means using express.raw on the webhook route instead of express.json.
Compare signatures in constant time
It is tempting to compare the two signatures with ===. A normal string comparison stops at the first character that differs, so it takes very slightly longer when more leading characters are correct. In principle an attacker can measure those differences across many requests and work out a valid signature piece by piece. This is called a timing attack.
A timing-safe comparison always takes the same time, wherever the first difference is. Node.js provides crypto.timingSafeEqual for this. It requires both inputs to have the same length and throws an error otherwise, so check the length first.
Stop replay attacks with the timestamp
A replay attack is when someone captures a genuine, correctly signed request and sends it again later. The signature is still valid, because nothing was changed.
The timestamp limits this. Because t is part of the signed message, an attacker cannot change it without breaking the signature. The receiver compares t with the current time and rejects anything too old. FormDB does not set a tolerance for you. Five minutes is a common choice, and your server's clock needs to be reasonably accurate for it to work.
A timestamp check still allows a replay inside the window. To close that gap, remember the X-FormDB-Delivery id of each delivery you have processed and ignore repeats. The same id is also in the body as id.
Complete Node.js example
This receiver uses Express. Install it with npm install express, save the file as server.mjs, and set the FORMDB_WEBHOOK_SECRET environment variable to your signing secret.
import crypto from "node:crypto";
import express from "express";
const SECRET = process.env.FORMDB_WEBHOOK_SECRET; // starts with whsec_
const TOLERANCE_SECONDS = 300;
const app = express();
const seenDeliveries = new Set(); // use a database in production
function parseSignatureHeader(header) {
const parts = {};
for (const piece of String(header || "").split(",")) {
const index = piece.indexOf("=");
if (index > 0) {
parts[piece.slice(0, index).trim()] = piece.slice(index + 1).trim();
}
}
return parts;
}
function isValidSignature(rawBody, header, secret) {
const { t, v1 } = parseSignatureHeader(header);
if (!t || !v1) return false;
const timestamp = Number(t);
if (!Number.isInteger(timestamp)) return false;
const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
if (ageSeconds > TOLERANCE_SECONDS) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.`)
.update(rawBody)
.digest();
const received = Buffer.from(v1, "hex");
if (received.length !== expected.length) return false;
return crypto.timingSafeEqual(received, expected);
}
app.post(
"/webhooks/formdb",
express.raw({ type: "application/json" }),
(req, res) => {
const signature = req.get("X-FormDB-Signature");
if (!isValidSignature(req.body, signature, SECRET)) {
return res.status(401).send("Invalid signature");
}
const deliveryId = req.get("X-FormDB-Delivery");
if (seenDeliveries.has(deliveryId)) {
return res.status(200).send("Already processed");
}
seenDeliveries.add(deliveryId);
const payload = JSON.parse(req.body.toString("utf8"));
if (payload.event === "submission.created") {
console.log("New submission for", payload.form.name);
console.log(payload.submission.data);
}
res.status(200).send("OK");
}
);
app.listen(3000, () => {
console.log("Listening on http://localhost:3000");
});With express.raw, req.body is a Buffer holding the exact bytes that were sent, which is what the HMAC needs. The JSON is parsed only after the signature has been accepted.
How retries and test deliveries behave
A few facts about FormDB deliveries affect how you write the handler:
- Respond with a
2xxstatus within 15 seconds. Do slow work after responding, or hand it to a queue. - Failures are retried. Timeouts, network errors and
5xx,408or429responses are retried with increasing delays, up to 6 attempts in total. Other4xxresponses and redirects are not retried. - Each attempt is signed again. The timestamp and signature are fresh on every attempt, so the timestamp check does not reject retries. The delivery id stays the same, which is why it works for spotting duplicates.
- "Send test" sends real data. The test button re-sends the form's latest submission with the event set to
test. It is signed the same way. The example above verifies it and then ignores it, because it only acts onsubmission.created. - File fields contain links. Uploaded files appear in
submission.fileswith a signed download URL that is valid for 7 days.
Troubleshooting a signature mismatch
If valid requests are rejected, check these in order:
- The body was parsed and re-serialised before hashing. Use the raw bytes.
- The secret is wrong. Copy it again, keep the
whsec_prefix, and check for stray spaces or quotes in the environment variable. - The secret was rotated. The old one stops working immediately.
- The message is built incorrectly. It is the timestamp, a full stop, then the body, with nothing else.
- The server clock is off by more than your tolerance.
The form's delivery log shows the status, attempt count and response code of recent deliveries, which helps confirm what your endpoint returned.
Next steps
The webhooks documentation has the full payload reference, and the endpoint reference describes what ends up in submission.data. Every plan includes signed webhooks, from one per form on Free to 25 on Business, as listed on the pricing page. If you are new to FormDB, create a free account to set up a form first.