Docs
Webhooks
Every submission, POSTed to your endpoint as JSON and signed with a secret unique to the form.
Turn it on
On the form's Notifications tab, switch on Webhook and enter your
Webhook URL. Use an https:// address. The URL must resolve to a public
address — private and internal network addresses are refused — and redirects are not followed.
The request
POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Formham-Timestamp: 1763467200
X-Formham-Signature-V2: sha256=6f1c…
{
"form_name": "Contact",
"submitted_at": "2026-11-18T12:00:00.000000Z",
"data": {
"name": "Jo Bloggs",
"email": "jo@example.com",
"message": "Could you call me back?",
"_source_url": "https:\/\/example.com\/contact",
"_page_title": "Contact us",
"_ip": "203.0.113.7"
}
}
data holds the fields exactly as your form sent them, plus _source_url,
_page_title (when the embed or the form sent one) and _ip, the address the
submission came from. The body is encoded with escaped slashes (\/), so always verify the
raw bytes you received, never a re-encoded copy.
Quarantined submissions are not sent until you release them from review.
Verifying the signature
Each form has its own signing secret, beginning whsec_. Find it in the admin panel at
https://app.formham.co.uk/admin: Forms → edit → Notifications → Signing
secret. It is created on the form's first delivery, or the first time an owner or admin opens
that tab. Regenerate replaces it immediately, so update your receiver at the same time.
To verify a request:
- Take the
X-Formham-Timestampheader and the raw request body. - Compute HMAC-SHA256 of
timestamp + "." + body, keyed with the form's secret, as lowercase hex, and prefix it withsha256=. - Compare it with
X-Formham-Signature-V2using a constant-time comparison. - Reject the request if the timestamp is more than five minutes from your clock. That stops a captured request being replayed later.
PHP
<?php
$secret = getenv('FORMHAM_WEBHOOK_SECRET'); // the form's whsec_… secret
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_FORMHAM_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_FORMHAM_SIGNATURE_V2'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (! hash_equals($expected, $signature) || abs(time() - (int) $timestamp) > 300) {
http_response_code(401);
exit;
}
$payload = json_decode($body, true);
// … store $payload['data']
http_response_code(200);
Node.js (Express)
const crypto = require('crypto');
const express = require('express');
const app = express();
// Keep the raw body: the signature is over the exact bytes sent.
app.post('/formham', express.raw({ type: 'application/json' }), (req, res) => {
const secret = process.env.FORMHAM_WEBHOOK_SECRET;
const timestamp = req.get('X-Formham-Timestamp') || '';
const signature = req.get('X-Formham-Signature-V2') || '';
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(timestamp + '.' + req.body.toString('utf8'))
.digest('hex');
const ok = signature.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
&& Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
if (!ok) return res.sendStatus(401);
const payload = JSON.parse(req.body.toString('utf8'));
// … store payload.data
res.sendStatus(200);
});
Python (Flask)
import hashlib, hmac, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["FORMHAM_WEBHOOK_SECRET"].encode()
def formham_webhook():
body = request.get_data() # raw bytes
timestamp = request.headers.get("X-Formham-Timestamp", "")
signature = request.headers.get("X-Formham-Signature-V2", "")
expected = "sha256=" + hmac.new(
SECRET, timestamp.encode() + b"." + body, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, signature):
abort(401)
if abs(time.time() - int(timestamp or 0)) > 300:
abort(401)
payload = request.get_json()
# … store payload["data"]
return "", 200
app.add_url_rule("/formham", view_func=formham_webhook, methods=["POST"])
The older signature
Some accounts also receive X-Formham-Signature: sha256= plus an HMAC of the body
alone, with a platform-wide secret and no timestamp. It is kept only so older receivers keep working and
will be removed. Verify X-Formham-Signature-V2 instead.
Responding, timeouts and retries
- Any 2xx response counts as delivered. Respond quickly and do slow work afterwards: we wait up to 15 seconds.
- A 5xx, a 429, a timeout or a connection error is retried: three attempts in total, the second about a minute after the first and the third about five minutes after that.
- Any other 4xx, or a redirect, is treated as a permanent failure and not retried.
- Every attempt is recorded in the submission's delivery log with its outcome, and a failed delivery can be resent from the dashboard once you have fixed the cause.
Retries mean you can occasionally receive the same submission twice. Per-form webhooks carry no
delivery ID, so de-duplicate on the content if that matters to you; integration hooks (below) carry
X-Formham-Delivery, which stays the same across retries.
Integration hooks (Zapier, Make, n8n)
Tools that subscribe to webhooks through an API use a richer payload. Subscriptions are created with an
API token from the app (see Integrations)
and must use HTTPS. They are signed the same way, and add two headers:
X-Formham-Event: submission.created and X-Formham-Delivery.
{
"event": "submission.created",
"sample": false,
"submission_id": 4182,
"receipt_id": "…",
"form": { "uuid": "…", "name": "Contact" },
"submitted_at": "2026-11-18T12:00:00+00:00",
"source_url": "https://example.com/contact",
"page_title": "Contact us",
"data": { "name": "Jo Bloggs", "email": "jo@example.com", "message": "…" },
"files": [ { "filename": "brief.pdf", "bytes": 48213, "mime": "application/pdf", "download_url": "…" } ]
}
A 410 Gone response unsubscribes the hook straight away, and a hook that fails ten times in
a row is switched off.