Skip to main content

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.