Webhooks
Webhooks deliver events to your URL as they happen — a lead was scored, a repeat message updated it, a message was junk. Every delivery is signed, retried on failure and logged.
Add a destination
curl -X POST https://core.leadveyor.com/v1/destinations \
-H "Authorization: Bearer lv_live_…" \
-H "Content-Type: application/json" \
-d '{
"url": "https://crm.example.com/leadveyor-webhook",
"events": ["lead.scored", "lead.outcome_recorded"],
"filter": { "field": "evaluation.tier", "op": "in", "value": ["hot", "warm"] }
}'
The response contains the signing secret (whsec_…) — it is shown only once; POST /v1/destinations/{id}/rotate-secret issues a new one. filter uses the same conditions as profiles, evaluated on the event's object. Send a test event with POST /v1/destinations/{id}/test.
Events
| Event | When |
|---|---|
lead.created | A new lead was extracted. |
lead.updated | A lead changed: a repeat message was merged into it, or it was reprocessed. previous has the earlier evaluation. |
lead.scored | A lead got an evaluation (after created or updated). |
lead.outcome_recorded | An outcome was recorded or removed. previous has the earlier outcome. |
inbound.junk | A message was classified as junk or not a lead. |
inbound.failed | A message failed after all retries. |
usage.threshold_reached | The account used 80% or 100% of its plan's leads this period (once each; sent to every workspace). |
Subscribe to prefixes with *, for example lead.*.
Payload
{
"object": "event",
"id": "evt_6Gk2Pq9Tz4Lm1Wx8Rc3Vn7Bd",
"type": "lead.scored",
"livemode": true,
"workspaceId": "ws_1Bq7Xn4KpRz9Lc2Vt6Hy0Mde",
"createdAt": "2026-11-02T09:30:00.000Z",
"data": {
"object": { "object": "lead", "id": "lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr", "evaluation": { "score": 80, "tier": "hot" } }
}
}
data.object is the full lead or inbound, as the API returns it. Each request also has the headers Leadveyor-Event-Id and Leadveyor-Signature.
Verify the signature
Leadveyor-Signature looks like t=1793615400,v1=5f2a…: v1 is the HMAC-SHA256 of "<t>.<raw body>" with your secret, in hex. Reject requests whose signature doesn't match or whose t is more than 5 minutes old. Always use the raw request body, before JSON parsing.
SDK
import Leadveyor from '@leadveyor/sdk'
// Throws WebhookSignatureError if the signature is wrong or older than 5 minutes
const event = await Leadveyor.webhooks.constructEvent(rawBody, signatureHeader, secret)
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verifyLeadveyor(secret, header, rawBody) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const t = Number(parts.t)
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
return expected.length === parts.v1?.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}
Python
import hashlib, hmac, time
def verify_leadveyor(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts.get("t", 0))
if abs(time.time() - t) > 300:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
Retries
Respond with any 2xx status within 10 seconds. Anything else is retried with growing delays — 1, 2, 4… up to 64 minutes, 8 attempts in all (about 2 hours). Use Leadveyor-Event-Id to ignore duplicates. A destination that fails 10 deliveries in a row is disabled; re-enable it with PATCH /v1/destinations/{id} and { "status": "active" }. The delivery log (GET /v1/destinations/{id}/deliveries) shows every attempt with the response, and any delivery can be sent again.
Webhook URLs must be public https addresses.
Prefer polling? GET /v1/events returns the same events for the last 30 days, newest first.