API & webhooks

For developers on the Pro plan, Cleartix offers a REST API and webhooks so you can connect ticketing to your own systems.

API keys

Create API keys under Settings to use the Cleartix REST API. With a key you can read your data from your own code or tools — your events, orders, attendees and per-event sales stats (tickets sold, check-ins and revenue, broken down by ticket type, without any attendee data) — to power dashboards, sync a CRM or build a custom report. Each key gets its own scopes, so you can hand an integration exactly the access it needs — for example only the aggregated sales stats.

Webhooks

Rather than polling the API, register webhooks so Cleartix notifies your endpoint when something happens, for example:

• A ticket sold
• An attendee checked in
• An order refunded

When the event occurs, Cleartix sends a request to your URL. Deliveries are signed, so you can verify each one really came from Cleartix, and they're retried if your endpoint is temporarily down — so a brief outage won't lose an event.

Webhook payloads

Every webhook is an HTTP POST whose JSON body uses the same envelope — only event and data change:

{
  "id": "evt_3f9a2b7c1d4e5f60",
  "event": "ticket.sold",
  "created_at": "2026-06-12T14:05:00.000Z",
  "organization_id": "org_abc123",
  "data": {}
}

Two headers travel with every request:

• X-ClearTix-Signature — sha256= followed by the HMAC-SHA256 of the raw request body, keyed with your endpoint's signing secret. Verify it before trusting a payload.
• X-ClearTix-Event — the event type, e.g. ticket.sold.

The data object depends on the event. Each event below shows an example data and its JSON Schema.

ticket.sold — ticket purchased and paid

{ "orderId": "ord_9f8e7d6c", "ticketCount": 2, "totalAmount": "50.00" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ticket.sold · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "ticketCount", "totalAmount"],
  "properties": {
    "orderId": { "type": "string" },
    "ticketCount": { "type": "integer", "minimum": 0 },
    "totalAmount": { "type": "string", "description": "Decimal total as a string, e.g. \"50.00\" (\"0\" for free orders)" }
  }
}

ticket.checked_in — attendee checked in at the event

{ "ticketId": "tkt_1a2b3c4d", "eventId": "ev_5e6f7a8b", "checkedInAt": "2026-06-12T14:05:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ticket.checked_in · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["ticketId", "eventId", "checkedInAt"],
  "properties": {
    "ticketId": { "type": "string" },
    "eventId": { "type": "string" },
    "checkedInAt": { "type": "string", "format": "date-time" }
  }
}

ticket.refunded — ticket refunded

{ "orderId": "ord_9f8e7d6c", "refundRef": "re_4d3c2b1a", "refundAmount": 2500 }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ticket.refunded · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "refundRef", "refundAmount"],
  "properties": {
    "orderId": { "type": "string" },
    "refundRef": { "type": "string", "description": "Provider refund reference" },
    "refundAmount": { "type": "integer", "description": "Refunded amount in cents" }
  }
}

order.created — order confirmed (including free orders)

{ "orderId": "ord_9f8e7d6c", "status": "paid" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "order.created · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "status"],
  "properties": {
    "orderId": { "type": "string" },
    "status": { "type": "string", "enum": ["paid"] }
  }
}

event.published — event published and live

{ "eventId": "ev_5e6f7a8b", "eventName": "Summer Yoga Retreat", "startAt": "2026-07-01T09:00:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "event.published · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["eventId", "eventName", "startAt"],
  "properties": {
    "eventId": { "type": "string" },
    "eventName": { "type": "string" },
    "startAt": { "type": "string", "format": "date-time" }
  }
}

Widgets via the API

Everything you can do with events widgets in the dashboard is also available over the API, so a website integration — for example a WordPress plugin — can create and place widgets without anyone copying snippets by hand. Keys need the widgets:read scope to list widgets and widgets:write to create, change or delete them.

A widget body uses the same fields as the dashboard form:

{
  "name": "Homepage",
  "view": "list",
  "selectionMode": "templates",
  "eventTemplateIds": ["tpl_abc123"],
  "dateFrom": "2026-10-01T00:00:00.000Z",
  "theme": { "primaryColor": "#4f46e5", "borderRadius": "md" },
  "defaultLocale": "nl"
}

selectionMode is one of all_upcoming, templates (with eventTemplateIds), manual (with eventIds) or location (with locationIds); view is list or calendar. Every widget the API returns carries an embed block with the loader script URL, the iframe URL, a ready-to-paste snippet and the data-* attributes the script reads — render either the snippet or your own <script>/<iframe> from those values. Because the snippet only references the widget by ID, later changes through the API or the dashboard show up on the website immediately.

OpenAPI specification

The full API is described in a machine-readable OpenAPI 3.1 document at https://cleartix.io/api/v1/openapi.json. Import it into Postman or Swagger UI to explore the endpoints, or feed it to a client generator for your language. Every operation lists the scope it needs and the exact request and response shapes.

Keep keys safe

An API key acts on behalf of your organisation, so treat it like a password:

1. Never commit it to source control or share it publicly.
2. Use a separate key per integration where you can.
3. Rotate a key immediately if it leaks, and delete keys you no longer use.