Webhook events

OverviewCopy Anchor Link

Members with the owner or manager role add endpoints in the dashboard and choose which events each one receives.

• 52 events in 8 groups.
• Delivery is at least once: the same event can arrive more than once, so deduplicate on Speakline-Event-Id.
• The address must use https; redirects are not followed.

RequestCopy Anchor Link

A delivery counts as successful when the endpoint answers 2xx within 5 seconds.

POST /speakline-webhook HTTP/1.1
Content-Type: application/json
User-Agent: Speakline-Webhooks/1.0
Speakline-Event-Type: lead.created
Speakline-Event-Id: 0f6a2c4e-8b1d-4e3f-9a5c-7d2e1b0f4c6a
Speakline-Delivery-Id: 3c9d2b7e-41f0-4a8e-b6d5-9e2c7a1f0b84
Speakline-Signature: t=1793572520,v1=5f2c…

Event envelopeCopy Anchor Link

The body is a JSON envelope with the same fields for every event; event-specific fields sit in payload.

{
  "event_id": "0f6a2c4e-8b1d-4e3f-9a5c-7d2e1b0f4c6a",
  "event_type": "lead.created",
  "schema_version": 1,
  "stream": "leads",
  "company_id": "7a3e5c1b-9d2f-4b8a-a6e4-c0f2d8b6a4e2",
  "occurred_at": "2026-10-23T14:02:11.482000+00:00",
  "context": { "lead_id": "5e1d9a3c-7b2f-4c8e-9a61-3f0b2d4c6e81" },
  "payload": {
    "id": "5e1d9a3c-7b2f-4c8e-9a61-3f0b2d4c6e81",
    "full_name": "Emma Clarke",
    "phone": "+442079460344",
    "email": "emma@example.com",
    "source": "inbound_voice",
    "status": "new",
    "language": "en",
    "created_at": "2026-10-23T14:02:11.482000+00:00"
  }
}

Verifying signaturesCopy Anchor Link

The Speakline-Signature header carries t (a Unix timestamp) and v1 (the signature). The signature is HMAC-SHA256 over t, a dot and the raw request body, keyed with the endpoint's secret and written as hex. Every attempt is signed again with a new timestamp.

• Verify against the raw body, before parsing the JSON.
• Compare in constant time.
• We recommend rejecting requests older than 300 seconds.
• The secret starts with whsec_ and is shown once, when it is created or rotated; rotating it invalidates the old one at once.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (string or Buffer), before JSON.parse.
export function verifySpeaklineSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest();
  const received = Buffer.from(parts.v1 ?? "", "hex");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

RetriesCopy Anchor Link

Non-2xx responses, timeouts and connection errors count as failures, and the delivery is retried at the intervals below.

If all six attempts fail, the delivery is marked exhausted. The endpoint stays on, and the workspace's owners and managers are notified (at most once a day per endpoint). You can resend any delivery from its history in the dashboard.

Event filterCopy Anchor Link

Each endpoint selects its events with glob patterns. The default * means every event; an empty list sends none. Every pattern must match at least one event.

Event catalogueCopy Anchor Link

Call centerCopy Anchor Link

CallsCopy Anchor Link

VoicemailsCopy Anchor Link

MessagingCopy Anchor Link

LeadsCopy Anchor Link

CampaignsCopy Anchor Link

AppointmentsCopy Anchor Link

Activity logCopy Anchor Link