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:

  1. Take the X-Formham-Timestamp header and the raw request body.
  2. Compute HMAC-SHA256 of timestamp + "." + body, keyed with the form's secret, as lowercase hex, and prefix it with sha256=.
  3. Compare it with X-Formham-Signature-V2 using a constant-time comparison.
  4. 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.