Help Center
The rules every destination follows, what your receiver has to do, and how to read the most common delivery failures.
Lead webhooks send each new lead to one address you choose. That address has to meet a few rules, and the most common problems all come from breaking one of them. This guide collects the rules in one place, so the Zapier, Make and n8n guides can stay short.
You are choosing the address that receives your leads, you want to know what your receiver has to answer, or a delivery failed and you want to know why.
One destination per account. Saving a new address replaces the old one and creates a new signing secret, and sends already waiting from the old setup are cancelled.
Your address receives one JSON POST per lead. The receiver answers, and the answer decides what happens next.
Every request carries three headers: webhook-id, webhook-timestamp and webhook-signature. The body holds the event id, the event type, a schema version, the capture time and the lead data.
The signature follows the Standard Webhooks format. To check it, remove whsec_ from your signing secret and base64 decode the rest. Then compute an HMAC SHA-256 value over webhook-id, a dot, webhook-timestamp, a dot and the raw body. The result, written in base64 with v1, in front, must match the signature header. Your tool has to hash the body exactly as it arrived, before any parsing, otherwise the value will not match.
A retry or a replay keeps the same webhook-id and the same body, with a fresh webhook-timestamp. Treat the event id as the identity of the lead event, and drop an event id you have already handled.
Deliveries can also arrive out of order, so do not rely on arrival time. Sort by occurred_at when the order matters, and keep the event id to recognise a repeat.
Only one kind of event is sent, lead.created. A test uses the type webhook.test and carries a synthetic marker instead.
A test event carries the same data structure as a real lead, so you can build your field mapping from it. Its values are invented and every identifier is null: data.lead.id, data.lead.duplicate_of_lead_id, data.card.id and data.card.block_id. Because those ids are null, any rule you build on a card id will treat a test as a stranger to that card. Route tests to a test path and never let one become a real contact.
When your mapping is ready, capture one lead through your own published card and watch it arrive. That is the only way to confirm the whole path, from the form to your tool to the record.
A visitor may send a message without agreeing to marketing. Check data.consent.marketing_consent_at before you add the contact to a list. When it is null, the visitor did not agree, even when their email address is present.
Automation tools answer the request first and do the work afterwards. That is what keeps the answer fast, and it means a delivery can be marked Delivered while the record is still missing, or while your own signature check has rejected the request a moment later.
Lead history is the transport record, not the outcome record. Read the tool's own history whenever you need to know what happened to a lead: Zapier's task history, Make's scenario run history, or n8n's execution list. All three show each run and each step.
A delivery marked Delivered is therefore worth checking after you change a filter. The request arrived, and the tool may still have dropped it on purpose.
The developer guide at /api-documentation/lead-webhooks documents every header, every payload field, the retry table, the test event and ready made PHP and Node.js verification snippets.
Paste this function into your service, or into a code step in a tool such as Pipedream, and call it with the request headers, the raw body text, your signing secret and the current time in seconds.
The body must be the exact text that arrived. Do not parse it first and do not re-write it, because the signature covers those exact bytes.
const crypto = require('crypto');
function verifyZappedWebhook({ headers, rawBody, signingSecret, nowSeconds }) {
const key = Buffer.from(String(signingSecret).slice(6), 'base64');
const id = String(headers['webhook-id'] || '');
const time = String(headers['webhook-timestamp'] || '');
const fresh = Math.abs(nowSeconds-Number(time)) <= 300;
let verified = false;
if (key.length === 32 && id && time && rawBody && fresh) {
const expected = crypto.createHmac('sha256', key)
.update(id + '.' + time + '.' + rawBody)
.digest();
verified = String(headers['webhook-signature'] || '').split(' ').some(function (part) {
if (part.indexOf('v1,') !== 0) return false;
const given = Buffer.from(part.slice(3), 'base64');
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
}
return { verified: verified, event_id: id };
}In Pipedream, the HTTP trigger parses a JSON body before your step sees it, so ask Pipedream to save the original body and read it back. Add the query string ?pipedream_upload_body=1 to the endpoint address when you save it in Zapped, and the step reads the untouched bytes from steps.trigger.event.body.raw_body_url. In a code step, the call looks like this, and the raw bytes come from that URL rather than from the parsed body.
Keep the signing secret in an environment variable, never in the code text. Stop the step when verification fails, so nothing writes before the request is trusted.
const headers = steps.trigger.event.headers;
const rawUrl = steps.trigger.event.body.raw_body_url;
const rawBody = await (await fetch(rawUrl)).text();
const result = verifyZappedWebhook({
headers: headers,
rawBody: rawBody,
signingSecret: process.env.ZAPPED_SIGNING_SECRET,
nowSeconds: Math.floor(Date.now() / 1000),
});
if (!result.verified) {
await $.flow.exit('Signature rejected');
}Lead webhooks are included with Professional. Open Account, then Lead webhooks, and save your HTTPS destination to get started. Delivery begins only after you configure a destination and the service is available. Custom-plan access follows your agreement.
You can, as long as that address is HTTPS on port 443 with a public hostname and answers 2xx within a few seconds. A page that only serves a contact form will not work, because it has to accept a POST, read the signature and answer without a redirect.
It proves the receiver accepted the request. Tools such as Zapier, Make and n8n answer first and work afterwards, so the record in your CRM may still be missing. Check the tool's own history for the real result.
Yes, in effect. Send the webhook to one automation tool and let that tool branch to each system. The account itself has one destination.
Anyone who learns your address can post to it. The signature is what proves a request came from Zapped, so verify it before you create a record, especially when the tool lets a stranger reach your data.
Was this guide helpful?