Webhooks
Register an HTTPS endpoint and Ticket Tool will POST a signed JSON payload whenever a subscribed event occurs. Manage endpoints on the Webhooks tab of Settings & Access → API & Webhooks, or through the API.
Scopes for managing webhooks by API
Listing endpoints needs webhooks:read, and changing them needs
webhooks:write. Creating or updating an endpoint also needs tickets:read,
because deliveries carry ticket data. Revoking a token disables the endpoints
it created. See Authentication for tokens and
scopes.
Discord channel webhooks won't work
The endpoint must accept the JSON payload below. A Discord channel webhook URL
(discord.com/api/webhooks/...) only accepts Discord messages, so the
dashboard and API reject it. To post ticket events into a Discord channel, use
an automation rule or a flow instead.
Payload
{
"id": "clr2x9k0a0001s7f0h2p3q4r5",
"type": "TICKET_CREATED",
"createdAt": "2026-06-06T12:00:00.000Z",
"data": { "ticketId": "...", "ticketNumber": 42 }
}
Event catalog
Ticket lifecycle
TICKET_CREATED, TICKET_UPDATED,
TICKET_CLOSED, TICKET_REOPENED,
TICKET_CLAIMED, TICKET_UNCLAIMED,
TICKET_DELETED
Activity
TICKET_MESSAGE_CREATED, TICKET_PARTICIPANT_ADDED,
TICKET_PARTICIPANT_REMOVED, TICKET_RATING_CREATED
Subscribe to specific events when you create the endpoint, or leave the list empty to receive all of them.
Verifying signatures
Each delivery includes these signing headers, alongside an X-Webhook-Event
header carrying the event type:
X-TicketTool-Signature: <hex hmac-sha256>
X-TicketTool-Timestamp: <unix seconds>
X-Webhook-Event: <event type, e.g. TICKET_CREATED>
The signature is HMAC-SHA256(secret, "{timestamp}.{rawBody}"), hex encoded. Verify it with the signing secret shown once when you created the endpoint. rawBody has to be the request body exactly as it arrived: parse the JSON only after the check passes, because re-serializing it changes the bytes.
import crypto from "crypto";
function verify(rawBody: string, headers: Headers, secret: string): boolean {
const signature = headers.get("X-TicketTool-Signature") ?? "";
const timestampHeader = headers.get("X-TicketTool-Timestamp") ?? "";
const timestamp = Number(timestampHeader);
if (!timestampHeader || !Number.isFinite(timestamp)) return false;
// Reject replays older than 5 minutes
if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${timestampHeader}.${rawBody}`)
.digest("hex");
// timingSafeEqual throws when the lengths differ
const a = Buffer.from(expected);
const b = Buffer.from(signature);
if (a.length !== b.length) return false;
return crypto.timingSafeEqual(a, b);
}
Delivery, retries, and replay
Respond with any 2xx status to acknowledge. Failed deliveries retry with
exponential backoff (1m, 5m, 30m, 2h, 6h; up to 6 attempts). An endpoint that
fails 15 times in a row is disabled automatically. Every attempt is recorded, and
you can inspect history or re-send a delivery from the dashboard or the
/v1/webhooks/{id}/deliveries endpoints.