Webhooks: get events sent to your own URL
Add an endpoint, choose events, verify the signature, and understand retries.
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.
#Add an endpoint
Open Settings, Integrations, then the Webhooks tile
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.
localhostand private addresses are refused. Redirects are never followed.Tick the events you want
The page starts with A positive reply.
Save, then copy the signing secret
It starts with
whsec_and is shown once. Store it where your endpoint can read it.
#The events
| Event | When it fires |
|---|---|
| A lead replied | Any reply, before it's sorted |
| A positive reply | Interested, meeting booked or referral |
| A connection was accepted | Someone accepted a request |
| A campaign finished | Every lead has been through it |
| An account needs attention | Signed out, or LinkedIn asked for a security check |
| A connection request, message, follow, like or visit was sent | A campaign did one of these |
| A lead's tags changed | A tag was added or removed |
| A LinkedIn action succeeded or failed | Something 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
{
"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.
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
In the list of endpoints, choose Send test on yours
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.Answer with a
2xxstatusAnswer 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.