Español

Webhook-Based Lead Capture: A Practical Guide for Custom Integrations

The native integration you need doesn't exist. Your event platform, partner portal, or custom web application can send a webhook, and that's it. The form submission or registration event fires, a JSON payload goes somewhere, and your job is to make that somewhere be your CRM. For teams who prefer no-code tools before investing in custom webhook infrastructure, see Zapier vs n8n vs Make for Lead Capture Automation first.

Most documentation on this stops at "configure your endpoint URL." That gets you a working demo. It doesn't get you a production pipeline that handles retries, duplicate submissions, authentication failures, and CRM API timeouts without losing leads or creating duplicate records.

This guide covers the full implementation: receiver endpoint design, payload validation, HMAC signature verification, CRM upsert logic, idempotency handling, and the error patterns that will cause you problems if you don't address them upfront.

The examples use Node.js and Python where code is needed. The concepts apply to any language or framework.

When Webhooks Are the Right Choice

Before going deep on implementation, make sure webhooks are actually the right tool.

Use webhooks when:

  • Your lead source has no native CRM integration
  • You need custom field transformation logic that no-code tools can't handle
  • You're processing high volume where Zapier task costs become prohibitive
  • You need sub-second processing time (webhooks are near-real-time)
  • You want full control over dedup, routing, and error handling logic

Consider no-code tools instead when:

  • Volume is under 500 leads/day and Zapier/Make costs are acceptable
  • Your integration needs are straightforward field mapping
  • You don't have engineering resources to maintain custom code

If you're specifically connecting a CMS form to Salesforce without paying for premium connectors, Connecting Your CMS Form to Salesforce Without Paying for Premium Connectors covers the Salesforce Web-to-Lead and n8n approaches in detail.

The decision usually comes down to volume and custom logic requirements. Once you hit either threshold, webhooks become the cleaner long-term solution. Gartner's guidance on API integration architecture underlines that webhook-based event-driven patterns consistently outperform polling approaches for latency-sensitive data flows like lead capture.

Anatomy of a Webhook Lead Capture Pipeline

Here's the full flow before we get into implementation:

Lead Source (event platform, custom app, partner portal)
    │
    └─ Fires POST request with JSON payload to your endpoint
            │
            └─ Webhook Receiver (your server or serverless function)
                    │
                    ├─ 1. Validate request signature (HMAC)
                    ├─ 2. Parse and validate payload schema
                    ├─ 3. Check idempotency (is this a duplicate submission?)
                    ├─ 4. Transform fields to CRM format
                    ├─ 5. Look up existing contact in CRM
                    ├─ 6. Create or update contact (upsert)
                    ├─ 7. Return HTTP 200 immediately
                    └─ 8. Log result (success or failure) asynchronously

The key design principle: return HTTP 200 as fast as possible. Never do slow operations (CRM API calls, database lookups) synchronously inside the webhook handler. Use a queue or background job for those. More on why in the section on avoiding timeouts.

Step 1: Design Your Webhook Receiver Endpoint

Your receiver needs to be:

  • Publicly accessible (the lead source needs to POST to it)
  • HTTPS only (never accept webhooks over HTTP)
  • Always available during business hours at minimum
  • Fast to respond (under 5 seconds, ideally under 1 second)

Deployment options:

  • Serverless function (AWS Lambda, Vercel, Cloudflare Workers): Zero infrastructure to manage, scales to any volume, cold start latency is acceptable for webhooks
  • Express.js on a VPS: Simple if you already have server infrastructure
  • FastAPI on a VPS: Good Python option with automatic request validation

Here's a minimal receiver in Node.js that handles the basics:

// webhook-receiver.js (Express.js)
const express = require('express');
const crypto = require('crypto');
const { Queue } = require('bullmq'); // for async processing

const app = express();
app.use(express.json());

const leadQueue = new Queue('lead-processing');

app.post('/webhooks/leads', async (req, res) => {
  // 1. Verify signature immediately
  const signature = req.headers['x-webhook-signature'];
  if (!verifySignature(req.body, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 2. Basic payload presence check
  const { email, firstName, lastName } = req.body;
  if (!email) {
    return res.status(400).json({ error: 'Missing required field: email' });
  }

  // 3. Queue the actual processing — return 200 immediately
  await leadQueue.add('process-lead', req.body, {
    jobId: req.body.submissionId || generateId(), // idempotency key
    removeOnComplete: 100,
    removeOnFail: 50
  });

  // 4. Return 200 fast — sender considers this a success
  return res.status(200).json({ received: true });
});

And the equivalent in Python with FastAPI:

# webhook_receiver.py
from fastapi import FastAPI, Request, HTTPException, Header
import hmac, hashlib, json
from typing import Optional

app = FastAPI()

@app.post("/webhooks/leads")
async def receive_lead(
    request: Request,
    x_webhook_signature: Optional[str] = Header(None)
):
    body = await request.body()
    payload = await request.json()

    # Verify signature
    if not verify_signature(body, x_webhook_signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    # Basic validation
    if not payload.get("email"):
        raise HTTPException(status_code=400, detail="Missing required field: email")

    # Queue for async processing
    await queue_lead_processing(payload)

    return {"received": True}

Step 2: Validate the Payload Schema

Don't trust that every webhook delivery will have all the fields you expect. Lead sources can change their payload structure between releases. Fields can be null or missing. You need validation before any processing happens.

Define a required field schema and check it:

// Schema validation (Node.js)
function validateLeadPayload(payload) {
  const errors = [];

  // Required fields
  if (!payload.email && !payload.phone) {
    errors.push('At least one of email or phone is required');
  }

  // Type validation
  if (payload.email && !isValidEmail(payload.email)) {
    errors.push(`Invalid email format: ${payload.email}`);
  }

  // Field length limits (prevent garbage data)
  if (payload.firstName && payload.firstName.length > 100) {
    errors.push('firstName exceeds maximum length');
  }

  return {
    valid: errors.length === 0,
    errors: errors
  };
}

When validation fails, return HTTP 400 with a descriptive error. Don't silently drop the lead. The lead source should log 400 responses so you can debug payload issues.

Common payload validation rules:

  • At least one identity field (email or phone) must be present
  • Email format validation (regex check)
  • Phone number normalization (strip spaces, dashes, parentheses)
  • String field length limits to prevent garbage data
  • Numeric fields should actually be numbers (not strings)
  • Date fields should parse correctly if provided

Step 3: Authenticate the Sender with HMAC Verification

Any publicly accessible endpoint is a target for spam submissions. Without authentication, anyone who discovers your webhook URL can flood your CRM with fake leads.

HMAC (Hash-based Message Authentication Code) signature verification is the standard approach. The NIST guidelines on cryptographic standards describe HMAC as the recommended mechanism for message authentication in exactly this kind of scenario — authenticating messages over an untrusted channel without requiring a shared session. Here's how it works:

  1. When you set up the webhook in the lead source platform, it shows you a "webhook secret" — a shared secret key
  2. When the sender fires a webhook, it computes an HMAC signature of the request body using the shared secret
  3. It includes that signature in a request header (usually X-Webhook-Signature or X-Hub-Signature-256)
  4. Your receiver computes the same HMAC and compares

If the signatures match, the request is from the legitimate sender. If not, reject it.

// HMAC verification (Node.js)
function verifySignature(body, receivedSignature) {
  if (!receivedSignature) return false;

  const secret = process.env.WEBHOOK_SECRET;
  const bodyString = typeof body === 'string' ? body : JSON.stringify(body);

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(bodyString)
    .digest('hex');

  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'utf8'),
    Buffer.from(receivedSignature.replace('sha256=', ''), 'utf8')
  );
}

# HMAC verification (Python)
import hmac, hashlib, os

def verify_signature(body: bytes, received_signature: str) -> bool:
    if not received_signature:
        return False

    secret = os.environ.get('WEBHOOK_SECRET', '').encode()
    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
    clean_received = received_signature.replace('sha256=', '')

    return hmac.compare_digest(expected, clean_received)

Important: Use timingSafeEqual or compare_digest for the comparison, not ==. Direct string comparison is vulnerable to timing attacks that can expose your secret.

If your lead source doesn't support HMAC signatures, use an API key in the header instead: require a custom header like X-API-Key with a secret value. It's less secure than HMAC (it doesn't verify payload integrity) but it's far better than nothing.

Step 4: Handle Idempotency to Prevent Duplicate Leads

This is the problem that bites teams in production. Webhook senders retry failed deliveries. Network issues cause the same event to fire twice. Your receiver processes both and creates two CRM contacts. The same deduplication challenge applies across all capture channels — Deduping Leads From Multi-Channel Capture covers how to handle it at scale.

Idempotency means: processing the same request twice produces the same result as processing it once.

The mechanism is an idempotency key: a unique identifier for each webhook event. Most lead source platforms include this in the payload or headers (often called submissionId, eventId, or X-Idempotency-Key).

On your receiver side, track processed keys in a fast store (Redis is ideal, a database table works too):

// Idempotency check using Redis
const redis = require('redis');
const client = redis.createClient();

async function isAlreadyProcessed(idempotencyKey) {
  const exists = await client.get(`webhook:${idempotencyKey}`);
  return exists !== null;
}

async function markAsProcessed(idempotencyKey) {
  // Store for 24 hours — enough to catch retries
  await client.setEx(`webhook:${idempotencyKey}`, 86400, '1');
}

// In your processing job:
async function processLead(payload) {
  const key = payload.submissionId || payload.eventId;

  if (key && await isAlreadyProcessed(key)) {
    console.log(`Skipping duplicate submission: ${key}`);
    return; // Already processed — skip
  }

  // ... do the CRM write ...

  if (key) {
    await markAsProcessed(key);
  }
}

If the lead source doesn't provide an idempotency key, you can construct one from stable fields: ${email}:${submissionTimestamp} is usually unique enough.

Step 5: Write to CRM with Upsert Logic

The CRM write is the critical step, and it needs to handle three cases:

  1. New contact: The email or phone doesn't exist in the CRM. Create a new record.
  2. Existing contact — update: The contact exists. Update their record with new data from the webhook.
  3. Partial match: The contact might exist but you can't be sure (e.g., phone matches but email doesn't). Handle this case explicitly rather than blindly creating or updating.

HubSpot Upsert (using the Contacts API v3)

HubSpot's API has a built-in upsert via the batch/upsert endpoint that handles cases 1 and 2 automatically:

// HubSpot upsert (Node.js with axios)
async function upsertHubSpotContact(leadData) {
  const properties = {
    email: leadData.email,
    firstname: leadData.firstName,
    lastname: leadData.lastName,
    phone: leadData.phone,
    company: leadData.company,
    // Custom properties you've created:
    lead_source_channel: leadData.sourceChannel,
    webhook_submission_id: leadData.submissionId,
    lead_captured_at: new Date().toISOString()
  };

  // Remove undefined values
  Object.keys(properties).forEach(k =>
    properties[k] === undefined && delete properties[k]
  );

  const response = await axios.patch(
    `https://api.hubapi.com/crm/v3/objects/contacts/${encodeURIComponent(leadData.email)}?idProperty=email`,
    { properties },
    {
      headers: {
        'Authorization': `Bearer ${process.env.HUBSPOT_TOKEN}`,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data;
}

If the contact doesn't exist, HubSpot returns a 404 on PATCH. Catch that and POST to create:

async function writeLeadToHubSpot(leadData) {
  try {
    // Try to update existing contact
    return await upsertHubSpotContact(leadData);
  } catch (error) {
    if (error.response?.status === 404) {
      // Contact doesn't exist — create new
      return await createHubSpotContact(leadData);
    }
    throw error; // Re-throw other errors
  }
}

Salesforce Upsert (using External ID)

For Salesforce, the cleanest approach is to use an External ID field on the Lead object. Create a custom field Webhook_Submission_ID__c and configure it as an External ID.

Then use the upsert endpoint: PATCH /services/data/v59.0/sobjects/Lead/Webhook_Submission_ID__c/{submissionId}

This creates or updates based on the external ID. No separate lookup needed.

Step 6: Return HTTP 200 Immediately and Process Asynchronously

This deserves its own section because getting it wrong causes real problems.

When your webhook receiver returns an HTTP response, the sender marks the webhook delivery as succeeded or failed based on that response. If you return 200, the sender moves on. If you return 500, the sender retries.

The problem: CRM API calls take 200-1000ms. Database lookups take time. If you do all of that synchronously inside the webhook handler, you risk:

  • Timeouts: Most webhook senders have a 5-10 second response timeout. If your CRM API is slow, you'll timeout and the sender will retry, causing duplicate processing.
  • Cascading failures: If the CRM API is down, your webhook handler returns 500, the sender retries, and you get a flood of retries when the CRM comes back up.

The solution is to return 200 immediately and process asynchronously:

app.post('/webhooks/leads', async (req, res) => {
  // Validate signature and basic payload — fast operations
  if (!verifySignature(req.body, req.headers['x-webhook-signature'])) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Queue for async processing — fast operation
  await leadQueue.add('process-lead', req.body, {
    jobId: req.body.submissionId
  });

  // Return 200 immediately — sender considers this a success
  return res.status(200).json({ received: true });
});

// This runs asynchronously in a worker
leadQueue.process('process-lead', async (job) => {
  const leadData = job.data;
  await idempotencyCheck(leadData.submissionId);
  await transformFields(leadData);
  await writeLeadToCRM(leadData);
  await logResult(leadData);
});

The queue (BullMQ in the Node.js example) handles retries on failure, but now they're internal retries within your system, not webhook delivery retries from the sender.

Common Pitfalls

Not validating webhook signatures: If you skip HMAC verification, anyone can POST fake leads to your endpoint. This isn't theoretical. Bots discover webhook endpoints and test them regularly.

Synchronous CRM writes in the handler: This causes timeouts and forces webhook retries. Always use a queue or background job.

Missing idempotency: The same lead written twice on retry. This creates duplicate CRM records that are expensive to clean up at scale.

Silent failures: If the CRM write fails and you don't log it with enough detail to debug, you lose leads with no indication anything went wrong. Log every failure with the full payload and error message.

Not handling the 404-on-upsert case: Writing update-only logic that fails silently when the contact doesn't exist, instead of falling back to create.

Webhook Receiver Scaffold (Node.js)

// Complete scaffold — adapt to your needs

const express = require('express');
const crypto = require('crypto');
const { Queue, Worker } = require('bullmq');
const { createClient } = require('redis');

const app = express();
app.use(express.raw({ type: 'application/json' })); // Keep raw body for HMAC

const redis = createClient({ url: process.env.REDIS_URL });
const leadQueue = new Queue('leads', { connection: redis });

// Receiver endpoint
app.post('/webhooks/leads', async (req, res) => {
  const rawBody = req.body;
  const payload = JSON.parse(rawBody);
  const sig = req.headers['x-webhook-signature'];

  if (!verifyHmac(rawBody, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Signature invalid' });
  }

  if (!payload.email && !payload.phone) {
    return res.status(400).json({ error: 'Missing identity field' });
  }

  const jobId = payload.submissionId || `${payload.email}-${Date.now()}`;
  await leadQueue.add('process', payload, { jobId, attempts: 3 });

  return res.status(200).json({ ok: true });
});

// Worker
new Worker('leads', async (job) => {
  const lead = job.data;

  // Idempotency check
  const processed = await redis.get(`lead:${job.id}`);
  if (processed) return;

  // CRM write
  await writeLeadToCRM(lead);

  // Mark as processed
  await redis.setEx(`lead:${job.id}`, 86400, '1');
}, { connection: redis });

function verifyHmac(body, signature, secret) {
  if (!signature || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature.replace('sha256=', ''))
  );
}

app.listen(3000);

Measuring What Matters

Webhook delivery success rate: Your webhook management platform (or the sender's dashboard) should show success rate. Target 99.9%+. Failures below this threshold indicate a receiver availability or timeout issue. Forbes Technology Council analysis of data pipeline reliability finds that even a 0.5% failure rate in a high-volume lead pipeline translates to meaningful revenue risk at scale — reinforcing why retry handling and idempotency are non-optional.

Duplicate record rate: Check your CRM weekly for contacts with identical email or phone. Any duplicates indicate your idempotency logic isn't working correctly.

Average processing latency: Time from webhook receipt to CRM record creation. Should be under 30 seconds for queue-based processing, under 5 seconds for synchronous.

Payload validation failure rate: How often are incoming webhooks missing required fields or failing schema validation? High rates indicate the sender's payload structure has changed and needs a mapping update.

Learn More