Webhooks

How it works

A webhook is an export destination, like Instantly or HubSpot. Choose Webhook when you export a segment of leads, or as a monitor's destination to receive each run's new businesses. We POST the leads in batches of 200. The segment's rules apply exactly as for a file: the email grades you chose (Verified only by default), your do-not-contact list, one row per business.

Payload

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-LeadGrid-Signature: sha256=5d1e0c…

{
  "source": "leadgrid",
  "export_id": 3141,
  "count": 200,
  "leads": [
    {
      "email": "hello@brightsmile.example",
      "email_grade": "valid",
      "business": "Bright Smile Dental",
      "category": "Dentist",
      "phone": "+15125550142",
      "website": "https://brightsmile.example/",
      "city": "Austin",
      "state": "Texas",
      "country": "US",
      "in_area": true,
      "place_id": 48213,
      "google_place_id": "ChIJ…"
    }
  ]
}

Each item in leads is the same record our CSV exports use (the full field list is below). Delivering a Verified email uses a checked-email credit the first time, as with any export.

Signing and verification

In the app, open Settings → Integrations → Webhook and generate a signing secret. From then on every request carries X-LeadGrid-Signature: sha256=<hex>, an HMAC-SHA256 of the raw request body keyed with your secret. Recompute it and compare in constant time; reject anything that doesn't match. You can rotate or remove the secret at any time.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.LEADRAFT_WEBHOOK_SECRET;

// Verify against the raw body, before any JSON parsing.
app.post("/leadraft", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const given = req.get("X-LeadGrid-Signature") ?? "";
  const ok = given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const { leads } = JSON.parse(req.body.toString("utf8"));
  // Upsert on place_id: a retried batch can arrive twice.
  res.status(200).end();
});

Delivery and retries

• Answer with any 2xx within 30 seconds to accept a batch.
• Network errors and 5xx answers are retried up to 3 attempts in total, waiting 1 s then 2 s. A 4xx answer stops the push.
• Redirects aren't followed: give us your endpoint's final URL.
• The URL must be a public http(s) address; private and local networks are refused.
• A batch can arrive more than once (a retried or resumed push), so make your handler idempotent: upsert on place_id.

Lead fields