Webhooks

Signed ticket.created and ticket.updated events, POSTed to your HTTPS endpoint and retried with backoff until it answers 2xx.

Webhooks send ticket events to your systems as tickets change: to keep a data warehouse in sync, open an issue in another tool, or notify a team.

Setting up

Owners and admins add webhooks under Settings > Channels & API > Webhooks with a name (up to 80 characters) and an HTTPS endpoint. QuantCX generates the signing secret, shows the latest delivery's status per webhook, and lets you switch a webhook off or delete it.

The endpoint must be a full https:// URL on port 443, without a username or password, and resolve to a public address. Private and reserved networks are refused when you save and again on every delivery.

Events

EventSent when
ticket.createdA ticket is created.
ticket.updatedAnything on a ticket changes.

Tickets brought in by an import do not send events.

The request

POST with a JSON body:

<code>{ "id": "5d0c…", "event": "ticket.updated", "createdAt": "2026-11-11T09:30:12.123456+00:00", "data": { "ticket": { "id": "…", "number": 48, "status": "open", "priority": "high", "subject": "Refund", "channel": "email", "requesterName": "Jane Doe", "requesterEmail": "jane@example.com", "assignee": null, "team": null, "tags": ["billing"], "category": null, "agent": "…", "createdAt": "…", "updatedAt": "…" } } }</code>
HeaderValue
Content-Typeapplication/json
User-AgentQuantCX-Webhooks/1.0
X-QuantCX-Eventticket.created or ticket.updated
X-QuantCX-DeliveryThe delivery's id. The same on every retry of one delivery, so use it to de-duplicate.
X-QuantCX-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the signing secret>

Verifying the signature (Node)

<code>import { createHmac, timingSafeEqual } from "node:crypto"; // header: the X-QuantCX-Signature value, rawBody: the request body exactly as received export function fromQuantCX(rawBody, header, secret, toleranceSeconds = 300) { const parts = Object.fromEntries(header.split(",").map(p => p.trim().split("=", 2))); const t = Number(parts.t); if (!Number.isInteger(t) || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest(); const given = Buffer.from(parts.v1, "hex"); return given.length === expected.length && timingSafeEqual(given, expected); }</code>

Sign the raw body exactly as received, before parsing it. The timestamp is set when each attempt is sent, so a five-minute tolerance works for retries too.

Delivery and retries

  • Events are queued when the ticket changes and sent by a job that runs every minute.
  • Any 2xx answer counts as delivered. Only the status matters; at most 16 KB of your response is read.
  • Each attempt waits up to 10 seconds. A timeout, a network error, a non-2xx status or a redirect (3xx, never followed) is a failed attempt.
  • Failed deliveries are retried with exponential backoff: 30 seconds, then 1, 2, 4 minutes and so on, capped at 6 hours, for up to 8 attempts in total. After that the delivery is marked failed.
  • Deliveries can arrive out of order. Use the ticket's updatedAt to keep the newest state.