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.

  1. Open the form and go to the Integrations tab.
  2. In the Webhooks card, enter your URL under Add an endpoint, for example https://api.example.com/webhooks/formdb. It must start with http:// or https://. You can also give it a name.
  3. 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

id

The delivery ID. Same value as the X-FormDB-Delivery header.

event

submission.created or test.

createdAt

When this delivery attempt was made.

form

The form's ID and name.

submission.id

The submission ID.

submission.createdAt

When the submission was received.

submission.data

The field values exactly as stored. The honeypot and captcha token fields are not included.

submission.files

One entry per uploaded file. size is in bytes. url is a signed download link valid for 7 days.

submission.meta

Country, the page the form was on, and the browser. Any of these can be null. The IP address is not included.

Events

Event

When

submission.created

A new submission was accepted.

test

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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • t is the time the request was signed, in Unix seconds.
  • v1 is the signature, as lowercase hexadecimal.

To verify:

  1. Read the raw request body, exactly as received, before parsing it as JSON.
  2. Build the signed message: the value of t, a full stop, then the raw body.
  3. Calculate the HMAC-SHA256 of that message. The key is your full signing secret as text, including the whsec_ prefix.
  4. Compare your result with v1 using a constant-time comparison.
  5. Optionally, reject requests whose t is 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

2xx

Marks the delivery as delivered.

Timeout or connection error

Retries.

5xx, 408 or 429

Retries.

Any other 4xx, or a 3xx

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 2xx. The status code is shown.

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

Ready to try it? Create a free account and send your first submission.