Webhook Documentation

SwiftChat pushes events over signed HTTPS webhooks. Configure endpoints in Developer Center → Webhooks.

Event categories

• message.* — sent, delivered, read, failed, edited, deleted, reaction
• conversation.* — created, assigned, closed, reopened
• deal.* — created, stage_changed, won, lost
• contact.* — created, updated, deleted
• campaign.* — started, completed, failed

Payload envelope

{
  "id": "evt_01H...",
  "type": "message.delivered",
  "created_at": "2026-07-18T09:12:04.213Z",
  "tenant_id": "ten_...",
  "data": { /* event-specific */ }
}

Signature verification

Every request includes:

X-SwiftChat-Signature: t=1721294524,v1=<hex-hmac-sha256>

Verify with timingSafeEqual:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(body: string, header: string, secret: string) {
  const [, ts, sig] = header.match(/t=(\d+),v1=([a-f0-9]+)/) ?? [];
  const expected = createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Reject if Math.abs(now - ts) > 300 seconds to prevent replays.

Delivery guarantees

• At-least-once delivery
• Exponential backoff — 30s, 2m, 10m, 30m, 2h, 6h, 12h, 24h
• After 8 failures the endpoint is auto-paused; you'll receive an alert
• Response must be 2xx within 10 seconds or delivery is retried

Idempotency

Deduplicate on event.id.