Skip to content

Webhooks: get events sent to your own URL

Add an endpoint, choose events, verify the signature, and understand retries.

3 min read · Updated November 18, 2026

A webhook is a web address of yours that HeyLeads calls the moment something happens: a reply, an accepted request, a finished campaign. Every call is signed, failed calls are retried, and every try is logged. If you use Slack, Zapier, Make or n8n, their own guides are easier; they're built on this same feature.

Settings, Integrations, Webhooks.

#Add an endpoint

  1. Open Settings, Integrations, then the Webhooks tile

  2. Choose Add endpoint and paste your address into the URL box

    It must be https, on the normal port (443), with no username or password in it, and reachable from the internet. localhost and private addresses are refused. Redirects are never followed.

  3. Tick the events you want

    The page starts with A positive reply.

  4. Save, then copy the signing secret

    It starts with whsec_ and is shown once. Store it where your endpoint can read it.

#The events

EventWhen it fires
A lead repliedAny reply, before it's sorted
A positive replyInterested, meeting booked or referral
A connection was acceptedSomeone accepted a request
A campaign finishedEvery lead has been through it
An account needs attentionSigned out, or LinkedIn asked for a security check
A connection request, message, follow, like or visit was sentA campaign did one of these
A lead's tags changedA tag was added or removed
A LinkedIn action succeeded or failedSomething you sent through the API went out, or didn't

Most people start with the positive reply, the reply and the accepted request. The full list, with the exact fields of each event, is in the developer guide.

#What a call looks like

POST to your URL
{
  "id": "5b0c6f7e-…",
  "event": "lead.replied",
  "workspaceId": "…",
  "data": { },
  "sentAt": "2026-11-18T14:00:00.000Z"
}

The id stays the same across retries, so use it to skip events you've already handled. Delivery is at least once, so a rare event can arrive twice.

#Verify the signature

Each call carries x-heylead-signature (a time and a signature made with your whsec_ secret) and x-heylead-timestamp. Check the signature against the raw body you received, compare in constant time, and reject calls older than 5 minutes.

Node.js
const crypto = require("node:crypto");

function verify(secret, signatureHeader, rawBody, nowSeconds = Math.floor(Date.now() / 1000), toleranceSeconds = 300) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || !parts.v1 || Math.abs(nowSeconds - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

#Test it

  1. In the list of endpoints, choose Send test on yours

  2. Read the Test event (preview) box

    It shows the exact request. A real test event (webhook.test) is also queued and reaches your address within seconds.

  3. Answer with a 2xx status

    Answer quickly. HeyLeads waits 10 seconds, so do the real work after replying.

#Retries and switching off

If your endpoint answers with an error, HeyLeads tries three more times, after 30 seconds, 5 minutes and 30 minutes. A reply such as 404, or a redirect, is final and isn't retried. After 20 failed deliveries in a row the endpoint is switched off. Fix it, then switch it back on with the toggle. The try-by-try log is available over the API at GET /api/v1/webhooks/{id}/deliveries.

Why didn't I get events for some things?

If you filtered the webhook to certain campaigns, events that belong to no campaign (account problems, API actions, tag changes) are hidden. Keep one unfiltered webhook for those.

How do I remove one?

Switch it off with the toggle to pause, or choose the trash icon, then Delete endpoint. Events stop at once and the secret is gone for good.

Was this article helpful?