# 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:

```json
{
  "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": "ann@example.com", "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](https://staging.formidable.sh/docs/api/).
File `url`s 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:

```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:

```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](https://staging.formidable.sh/docs/webhooks.md)*
