Webhooks
Send every FormDB submission to your own server with a webhook: setup, payload, signature verification, retries, the delivery log and tests.
This page shows how to send each submission to your own server with a webhook. It covers setup, the data you receive, how to verify that a request really came from FormDB, and what happens when a delivery fails.
A webhook is a message one system sends to another when something happens. Here, FormDB sends an HTTP POST request with the submission as JSON to a URL you choose, shortly after each submission arrives.
Every plan: Each form can send to 1 webhook on Free, 3 on Starter, 10 on Growth and 25 on Business.
Set up a webhook
You need the admin or owner role.
- Open the form and go to the Integrations tab.
- In the Webhooks card, enter your URL under Add an endpoint, for example
https://api.example.com/webhooks/formdb. It must start withhttp://orhttps://. You can also give it a name. - Click Add.
The webhook is active immediately. Each webhook has its own row with a switch to pause it without removing it. Repeat the steps to add more webhooks, up to your plan's limit.
Each webhook has its own signing secret that starts with whsec_. Open the webhook's actions menu and choose Show signing secret to copy it. You will need it to verify requests.
What triggers a webhook
- A webhook is sent for every accepted submission.
- Submissions flagged as spam, dropped by the honeypot or rejected are not sent.
- Deliveries happen in the background, after the visitor already has their response. A slow webhook never slows down your form.
The request
POST /webhooks/formdb
Content-Type: application/json
User-Agent: FormDB-Webhooks/1.0
X-FormDB-Event: submission.created
X-FormDB-Delivery: <delivery id>
X-FormDB-Signature: t=<unix seconds>,v1=<hex signature>Payload
{
"id": "<delivery id>",
"event": "submission.created",
"createdAt": "2026-11-17T10:00:03.123Z",
"form": { "id": "abc123def4", "name": "Contact form" },
"submission": {
"id": "<submission id>",
"createdAt": "2026-11-17T10:00:00.000Z",
"data": {
"name": "Ada",
"email": "ada@example.com",
"topics": ["a", "b"]
},
"files": [
{
"field": "resume",
"name": "cv.pdf",
"size": 48213,
"type": "application/pdf",
"url": "https://api.formdb.io/files/...?exp=...&sig=..."
}
],
"meta": {
"country": "DE",
"referer": "https://example.com/contact",
"userAgent": "Mozilla/5.0 ..."
}
}
}Field | Meaning |
|---|---|
| The delivery ID. Same value as the |
|
|
| When this delivery attempt was made. |
| The form's ID and name. |
| The submission ID. |
| When the submission was received. |
| The field values exactly as stored. The honeypot and captcha token fields are not included. |
| One entry per uploaded file. |
| Country, the page the form was on, and the browser. Any of these can be |
Events
Event | When |
|---|---|
| A new submission was accepted. |
| You clicked Send test in the dashboard. |
There are no other events. Webhooks are not sent when a submission is deleted, restored or marked as spam.
Verify the signature
Anyone who learns your webhook URL could send fake requests to it. To be sure a request came from FormDB, check its signature.
FormDB signs each request with HMAC-SHA256. An HMAC is a fingerprint calculated from a message and a secret key. Only someone who knows the secret can produce the right fingerprint, so if yours matches, the request is genuine and was not altered.
The X-FormDB-Signature header looks like this:
t=1700000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdtis the time the request was signed, in Unix seconds.v1is the signature, as lowercase hexadecimal.
To verify:
- Read the raw request body, exactly as received, before parsing it as JSON.
- Build the signed message: the value of
t, a full stop, then the raw body. - Calculate the HMAC-SHA256 of that message. The key is your full signing secret as text, including the
whsec_prefix. - Compare your result with
v1using a constant-time comparison. - Optionally, reject requests whose
tis too old. Five minutes is a common choice. This limits replay of a captured request.
Node.js example
This is a complete server with no dependencies. Save it as server.mjs, set the FORMDB_WEBHOOK_SECRET environment variable to your signing secret and run node server.mjs.
import crypto from "node:crypto";
import http from "node:http";
const SECRET = process.env.FORMDB_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SECONDS = 300;
function verifySignature(rawBody, header, secret) {
if (!header) return false;
const parts = Object.fromEntries(
header.split(",").map((part) => part.split("="))
);
if (!parts.t || !parts.v1) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
const expectedBuffer = Buffer.from(expected);
const receivedBuffer = Buffer.from(parts.v1);
if (expectedBuffer.length !== receivedBuffer.length) return false;
if (!crypto.timingSafeEqual(expectedBuffer, receivedBuffer)) return false;
const ageInSeconds = Math.abs(Date.now() / 1000 - Number(parts.t));
return ageInSeconds < TOLERANCE_SECONDS;
}
const server = http.createServer((req, res) => {
if (req.method !== "POST" || req.url !== "/webhooks/formdb") {
res.writeHead(404).end();
return;
}
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", () => {
const rawBody = Buffer.concat(chunks).toString("utf8");
const signature = req.headers["x-formdb-signature"];
if (!verifySignature(rawBody, signature, SECRET)) {
res.writeHead(401).end("Invalid signature");
return;
}
const payload = JSON.parse(rawBody);
if (payload.event === "submission.created") {
console.log("New submission", payload.submission.id, payload.submission.data);
}
res.writeHead(200).end("ok");
});
});
server.listen(3000, () => {
console.log("Listening on http://localhost:3000/webhooks/formdb");
});If you use a framework such as Express, make sure you verify against the raw body, not a parsed and re-serialised copy. The bytes must be identical.
Python example
import hashlib
import hmac
import time
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(part.split("=", 1) for part in header.split(","))
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
fresh = abs(time.time() - int(parts["t"])) < tolerance
return fresh and hmac.compare_digest(expected, parts["v1"])Pass the raw request bytes, the X-FormDB-Signature header and your signing secret.
Rotate the secret
If your secret may have leaked, open the webhook's actions menu and choose Rotate secret. The new secret takes effect immediately and the old one stops working, so update your server right away.
Respond quickly
Reply with any 2xx status to confirm receipt. FormDB waits up to 15 seconds for a response. If your processing takes longer, save the payload, reply 200 and do the work afterwards.
Redirects are not followed. A 3xx response counts as a failure.
Retries
If a delivery fails, FormDB tries again automatically.
Your endpoint's response | What FormDB does |
|---|---|
| Marks the delivery as delivered. |
Timeout or connection error | Retries. |
| Retries. |
Any other | Marks the delivery as failed. No retry. |
A delivery is attempted up to 6 times. The waits between attempts are 30 seconds, 1 minute, 2 minutes, 4 minutes and 8 minutes, so the last attempt happens about 15 minutes after the first. After the sixth failure the delivery is marked as failed and is not attempted again. A failed delivery cannot be re-sent by hand.
The delivery ID, in the X-FormDB-Delivery header and the body's id, stays the same across retries. Because a retry can arrive after your server already processed the first attempt, store the IDs you have handled and skip repeats. The timestamp and signature are new for each attempt.
The submission itself is never lost when a webhook fails. It stays in your inbox.
Delivery log
Once a form has deliveries, a Recent deliveries card appears at the bottom of the Integrations tab. It lists the 25 most recent deliveries for the form, across all integrations.
Status | Meaning |
|---|---|
Queued | Waiting for the first attempt. |
Retrying | At least one attempt failed and another is scheduled. Hover to see the last error. |
Delivered | Your endpoint answered with a |
Failed | No more attempts will be made. Hover to see the error, for example "Endpoint responded with 500". |
The log also shows the destination, the number of attempts and the time. Each delivery has one row that is updated after every attempt. Request and response bodies are not stored.
Send a test
Open the webhook's actions menu and choose Send test. FormDB sends the form's most recent real submission to your URL, with event set to test and the header X-FormDB-Event: test. The request is signed like any other.
The form needs at least one submission first. If it has none, send one from the Setup tab. Then check the delivery log for the result.
Limits
- Webhooks per form: 1 on Free, 3 on Starter, 10 on Growth and 25 on Business.
- Custom headers and custom payload formats are not supported.
- If the workspace moves to a plan with a lower limit, webhooks beyond the new limit are kept, but nothing is delivered to them until you upgrade again or remove others.
Next steps
- Google Sheets: send submissions to a spreadsheet without code.
- Endpoint reference: the submission endpoint that feeds your webhook.
- File uploads: how the signed file links in the payload work.
Ready to try it? Create a free account and send your first submission.