Setting Up the Lead Webhook
Updated Date:
What the Webhook Does
ClickSambo sends every Instant Form lead to your HTTPS address as JSON, with all form fields and the fraud analysis. Your CRM can keep the real leads and filter the suspicious ones. Every request is signed with HMAC-SHA256, so your system can verify it came from ClickSambo.
How to Set It Up
1. Go to Ads → Meta Ads → Lead Forms → Webhook and notifications.
2. Enter your Endpoint URL (HTTPS).
3. Enter a Signature key of at least 16 characters, or click Generate. Define the same key on your endpoint.
4. Click Verify and save. ClickSambo saves the address only after your endpoint answers the verification handshake correctly.
After saving, you can Send test lead, Pause the webhook, Change endpoint or key or Remove it.
Events and Headers
| Event | When it is sent |
|---|---|
lead.received | After a new lead is analysed |
lead.updated | After you mark a lead Real or Fake |
webhook.test | When you click Send test lead |
webhook.verify | During the handshake when saving |
Each request carries X-ClickSambo-Event, X-ClickSambo-Delivery, X-ClickSambo-Timestamp and X-ClickSambo-Signature headers. The signature is sha256= followed by the hex-encoded HMAC-SHA256 of the raw request body with your key.
Verification and Delivery Rules
| Event / field | What to do |
|---|---|
webhook.verify | Respond with HTTP 200 and JSON containing challenge and signature. The signature is sha256= plus the HMAC-SHA256 of the challenge value with your key. |
lead.received, lead.updated | Respond with HTTP 2xx within 15 seconds. Other responses are retried 3 times, and you can resend any lead from the dashboard. |
analysis.verdict, analysis.fraud_score | Filter leads in your CRM. The verdict is real or fraud. |
lead.fields | Carries every form question as submitted; e-mail, phone and full name are also normalised. |
Sample Code
The dashboard's integration guide includes Node.js, PHP and C# samples and the full payload template. A Node.js example:
// Node.js (Express) — raw body is required for signature verification
const crypto = require('crypto');
const SECRET = process.env.CLICKSAMBO_WEBHOOK_SECRET;
app.post('/clicksambo-leads', express.raw({ type: 'application/json' }), (req, res) => {
const raw = req.body.toString('utf8');
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(raw).digest('hex');
const given = req.get('X-ClickSambo-Signature') || '';
if (given.length !== expected.length ||
!crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
return res.status(401).end();
}
const data = JSON.parse(raw);
if (data.event === 'webhook.verify') {
const signature = 'sha256=' + crypto.createHmac('sha256', SECRET).update(data.challenge).digest('hex');
return res.json({ challenge: data.challenge, signature });
}
if (data.event === 'lead.received' || data.event === 'lead.updated') {
if (data.analysis.verdict === 'real') saveToCrm(data.lead);
else moveToQuarantine(data.lead, data.analysis);
}
res.status(200).end();
});