Lead webhooks

1. Remove whsec_ from your signing secret and base64 decode the rest. That is the key.
2. Compute HMAC SHA-256 over webhook-id.webhook-timestamp.body, using the raw body exactly as received.
3. Base64 encode it, prefix v1, and compare it in constant time with each space separated signature in the header. Accept the request when any one matches.
4. Reject timestamps more than five minutes from your clock, and ignore an event ID you already processed.

Any Standard Webhooks library can do this for you with the same secret, including headers with more than one signature.

Replacing your signing secret. Leads already waiting to be sent are kept and are signed with the new secret. For the next 24 hours every request also carries a second signature made with the previous secret, so a receiver that still has the old secret keeps accepting requests while you update it. After 24 hours only the new secret signs. Replacing the destination URL, disabling the destination or revoking it does not keep waiting leads.

PHP

$secret  = base64_decode(substr($signingSecret, 6)); // remove "whsec_"
$id      = $_SERVER['HTTP_WEBHOOK_ID'];
$time    = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body    = file_get_contents('php://input');
$expect  = 'v1,' . base64_encode(hash_hmac('sha256', "$id.$time.$body", $secret, true));
$given   = explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE']);

if (abs(time() - (int) $time) > 300 || !in_array(true, array_map(fn($s) => hash_equals($expect, $s), $given), true)) {
    http_response_code(400);
    exit;
}
http_response_code(204); // then process the lead

Node.js

import crypto from 'node:crypto';

// Use the raw request body exactly as received.
function verify(rawBody, headers, signingSecret) {
  const key = Buffer.from(signingSecret.slice('whsec_'.length), 'base64');
  const id = headers['webhook-id'];
  const time = headers['webhook-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(time)) > 300) return false;
  const expected = 'v1,' + crypto.createHmac('sha256', key).update(`${id}.${time}.${rawBody}`).digest('base64');
  return headers['webhook-signature'].split(' ').some((s) =>
    s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
}

Automatic retries wait 1 minute, 5 minutes, 15 minutes, 1 hour, 2 hours, 6 hours and 12 hours, with at most 8 attempts within 24 hours of the lead. Reply quickly with a 2xx and process the lead afterwards. Bodies are at most 128 KB.

Leads can arrive in a different order than they were captured, for example after a retry or during a burst of submissions. Use occurred_at when order matters, and the event ID to ignore repeats.

A test from the Test history tab arrives signed the same way, with "type": "webhook.test" and "synthetic": true. Its data has the same structure as a real lead, with invented values and every identifier set to null, so you can build your field mapping from it. No real lead is created. Handle it like a lead, or acknowledge and ignore it.

{
    "id": "evt_fedcba9876543210fedcba9876543210",
    "type": "webhook.test",
    "schema_version": 1,
    "synthetic": true,
    "occurred_at": "2026-09-24T14:10:00Z",
    "data": {
        "lead": {
            "id": null,
            "duplicate_of_lead_id": null,
            "capture_preset": "enquiry",
            "intent": "enquiry",
            "source_channel": "vcard",
            "name": "Example Contact",
            "email": "[email protected]",
            "phone": "+1 555 0100",
            "company": "Example Company",
            "message": "Invented sample data for a webhook connection test."
        },
        "card": {
            "id": null,
            "block_id": null,
            "name": "Example Card",
            "url_alias": "example-card"
        },
        "consent": {
            "notice_language": "english",
            "privacy_notice_version": 1,
            "marketing_consent_at": "2026-09-24T14:10:00Z",
            "marketing_consent_version": 1,
            "marketing_consent_source": "lead_form"
        },
        "custom_fields": {
            "schema_version": 1,
            "template_key": "project_enquiry",
            "intent": "enquiry",
            "form_headline": "Start a project",
            "answers": [
                {
                    "question_id": "q_0a1b2c3d4e5f",
                    "question_label": "Project budget",
                    "type": "single_choice",
                    "selected_options": [
                        {
                            "option_id": "o_0a1b2c3d4e5f",
                            "option_label": "Under 5000"
                        }
                    ]
                },
                {
                    "question_id": "q_1a2b3c4d5e6f",
                    "question_label": "Preferred start date",
                    "type": "short_text",
                    "value": "Next month"
                }
            ]
        }
    }
}