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

EventWhen
lead.createdA new lead was extracted.
lead.updatedA lead changed: a repeat message was merged into it, or it was reprocessed. previous has the earlier evaluation.
lead.scoredA lead got an evaluation (after created or updated).
lead.outcome_recordedAn outcome was recorded or removed. previous has the earlier outcome.
inbound.junkA message was classified as junk or not a lead.
inbound.failedA message failed after all retries.
usage.threshold_reachedThe 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.

Was this page helpful?