Docs / Guides
Webhooks
We POST each new submission to your HTTPS endpoint as signed JSON, and retry until you answer with a 2xx.
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
- Open the form's Webhooks page and add your endpoint URL. It must be
https://and reachable on the public internet. - Copy the signing secret. It starts with
whsec_and is shown once; you can reveal it again later from the same page. - Verify the signature on every request (below), then answer with any
2xxstatus within 10 seconds. - Do slow work (sending to a CRM, Slack and so on) after you answer, or in a queue.
The payload
typeis alwayssubmission.createdfor now.testistruefor test sends from the dashboard.data.idis the submission ID.data.form.idis the form ID from your snippet.fieldskeeps the order the visitor sent. Values are strings, or lists of strings for repeated names. Reserved fields such as_honeyare not included.replyTo,meta.origin,meta.refererandmeta.userAgentcan benull.- 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:
- Build the signed content:
webhook-id+.+webhook-timestamp+.+ the raw request body. - Compute an HMAC-SHA256 of it. The key is the part of your secret after
whsec_, base64-decoded. - Base64-encode the result.
webhook-signatureholds one or more space-separatedv1,<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. - Reject the request if
webhook-timestampis 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
3xxcounts as a failure. Use the final URL, including the trailing slash if your server redirects to it.