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
| Event | Sent when |
|---|---|
ticket.created | A ticket is created. |
ticket.updated | Anything on a ticket changes. |
Tickets brought in by an import do not send events.
The request
POST with a JSON body:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | QuantCX-Webhooks/1.0 |
X-QuantCX-Event | ticket.created or ticket.updated |
X-QuantCX-Delivery | The delivery's id. The same on every retry of one delivery, so use it to de-duplicate. |
X-QuantCX-Signature | t=<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
2xxanswer 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
updatedAtto keep the newest state.