Skip to content
Wrenform

Docs / Guides

Webhooks

We POST each new submission to your HTTPS endpoint as signed JSON, and retry until you answer with a 2xx.

Last updated 2026-11-14View as Markdown
POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Wrenform-Webhooks/1.0 (+https://wrenform.com/docs/webhooks)
webhook-id: 01JD3K2M9X7Q8R4T5V6W7Y8Z9A
webhook-timestamp: 1765880100
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

Webhooks are on the Pro (€12/month) and Agency (€29/month) plans. Each form can have up to 3 endpoints.

Steps

  1. Open the form's Webhooks page and add your endpoint URL. It must be https:// and reachable on the public internet.
  2. Copy the signing secret. It starts with whsec_ and is shown once; you can reveal it again later from the same page.
  3. Verify the signature on every request (below), then answer with any 2xx status within 10 seconds.
  4. Do slow work (sending to a CRM, Slack and so on) after you answer, or in a queue.

The payload

  • type is always submission.created for now. test is true for test sends from the dashboard.
  • data.id is the submission ID. data.form.id is the form ID from your snippet.
  • fields keeps the order the visitor sent. Values are strings, or lists of strings for repeated names. Reserved fields such as _honey are not included.
  • replyTo, meta.origin, meta.referer and meta.userAgent can be null.
  • We send webhooks only for submissions that land in Inbox. Spam, and submissions over your monthly quota, get none.

Verify the signature

We sign with the Standard Webhooks scheme:

  1. Build the signed content: webhook-id + . + webhook-timestamp + . + the raw request body.
  2. Compute an HMAC-SHA256 of it. The key is the part of your secret after whsec_, base64-decoded.
  3. Base64-encode the result. webhook-signature holds one or more space-separated v1,<signature> entries; accept the request if any one matches, comparing in constant time. There are two entries for 24 hours after you rotate the secret.
  4. Reject the request if webhook-timestamp is more than 5 minutes from your clock.

Use the raw body exactly as received. Parsing and re-serialising the JSON changes the bytes and breaks the signature.

import { createHmac, timingSafeEqual } from "node:crypto";

// headers: lower-case names, as Node gives them. rawBody: the body as a string, before any JSON parsing.
export function verifyWebhook(headers, rawBody, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;

  const now = Math.floor(Date.now() / 1000);
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 5 * 60) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();

  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

The Standard Webhooks project also publishes libraries that do this for you; pass them your whsec_ secret.

In Express, read the raw body with express.raw({ type: "application/json" }) and pass req.body.toString("utf8"). In Next.js route handlers, use await request.text().

Delivery and retries

Topic Rule
Success Any 2xx response within 10 seconds
Failure Any other status, a timeout, or a TLS, DNS or connection error
Retries After 1 min, 5 min, 30 min, 2 h, 6 h and 12 h: 7 attempts over about 21 hours. Then the delivery is abandoned
Auto-disable After 50 failed deliveries in a row, or 3 days of failures with no success. We email you; re-enable it on the Webhooks page
Order Not guaranteed
Duplicates Possible (at least once). De-duplicate by webhook-id; it stays the same across retries
Network HTTPS only, public IP addresses only. Redirects are not followed: a 3xx is a failure

The Webhooks page shows each delivery with its status code and the start of your response. You can retry an abandoned delivery, send a test, rotate the secret, or turn an endpoint off.

Test it

Press Send test on the Webhooks page. You get a real, signed request with "test": true, and the page shows your response.

Common problems

  • Every signature fails. Your framework parsed the JSON before you read the body. Verify against the raw bytes.
  • Fails only sometimes. Your server's clock is off by more than 5 minutes. Sync it with NTP.
  • The URL is refused. It isn't https://, or it points to a private, local or reserved address.
  • Deliveries time out. Answer first, then do the work. We wait 10 seconds at most.
  • A 3xx counts as a failure. Use the final URL, including the trailing slash if your server redirects to it.

Next steps

  • Errors: codes the form endpoint returns.
  • Privacy: what a webhook sends to your server, for your records.

Something wrong or unclear on this page? Report a problem: write to hello [at] wrenform.com with the page address (/docs/webhooks).