Webhooks
A webhook sends each new submission to a URL you choose - your own server, a CRM, Slack, Zapier, Make or n8n - the moment it passes the spam check. Your notification emails keep working alongside it.
Set them up per form: form → Webhooks. Webhooks are on paid plans.
What we send
A POST with a JSON body:
{
"event": "submission.created",
"created_at": "2026-11-18T09:12:45+00:00",
"form": {"id": "YOUR_FORM_ID", "name": "Contact sales"},
"submission": {
"id": 4182,
"created_at": "2026-11-18T09:12:44+00:00",
"is_spam": false,
"is_read": false,
"spam_reasons": [],
"data": {"name": "Ann", "email": "[email protected]", "message": "Hello"},
"files": [{"id": 77, "field": "cv", "name": "cv.pdf", "size": 48211,
"content_type": "application/pdf",
"url": "https://staging-api.formidable.sh/api/v1/forms/YOUR_FORM_ID/entries/4182/files/77/"}],
"notes": {}
}
}
The submission has the same shape as in the API.
File urls need an API token (entries:read) to download.
Headers:
| Header | Value |
|---|---|
X-Formidable-Event |
submission.created (or test from the "Send test" button) |
X-Formidable-Delivery |
A unique id for this delivery - use it to ignore duplicates |
X-Formidable-Signature |
t=<unix time>,v1=<signature> - see below |
Answer with any 2xx status within 10 seconds. Redirects aren't followed.
When it's sent: after the spam check. Spam isn't sent unless you tick "Send spam too"; a submission you later mark "Not spam" is sent then. Submissions held because your account is over its monthly limit aren't sent.
Checking the signature
Every request is signed with your webhook's signing secret (shown on the
Webhooks page). Compute HMAC-SHA256(secret, "<t>.<raw body>") and compare
it with v1. Reject requests whose t is more than 5 minutes old.
Python:
import hashlib, hmac, time
def verify(secret, raw_body: bytes, header: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
expected = hmac.new(secret.encode(), f'{parts["t"]}.'.encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
Node.js:
const crypto = require('crypto');
function verify(secret, rawBody, header) {
const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
Use the raw request body, before any JSON parsing.
Retries
If your server doesn't answer 2xx, we try again after 1 minute, 5 minutes,
30 minutes, 2 hours, 6 hours and 24 hours. Every attempt is listed under
"Recent deliveries", where you can also retry by hand. After 10 deliveries in
a row fail, the webhook switches itself off and we email you; switch it back
on once your server is fixed.
Webhook URLs must be public http(s) addresses - private and local network
addresses are refused.
Machine-readable: https://staging.formidable.sh/docs/webhooks.md