How can we help?

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

EventWhen it is sent
lead.receivedAfter a new lead is analysed
lead.updatedAfter you mark a lead Real or Fake
webhook.testWhen you click Send test lead
webhook.verifyDuring 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 / fieldWhat to do
webhook.verifyRespond 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.updatedRespond 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_scoreFilter leads in your CRM. The verdict is real or fraud.
lead.fieldsCarries 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();
});
Partner Program

Ready to grow with ClickSambo?

Join our partner program and turn ad-fraud protection into a scalable, recurring revenue stream.

Apply to the program

ClickSambo support is available!

Whatsapp Chat