Skip to content
Docs menu

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