API & webhooks

Voor ontwikkelaars op het Pro-plan biedt Cleartix een REST API en webhooks, zodat je ticketing aan je eigen systemen kunt koppelen.

API-sleutels

Maak API-sleutels aan onder Settings om de Cleartix REST API te gebruiken. Met een sleutel kun je je data uitlezen vanuit je eigen code of tools — je evenementen, bestellingen en deelnemers — om dashboards te voeden, een CRM te synchroniseren of een eigen rapport te bouwen.

Webhooks

In plaats van de API te pollen, registreer je webhooks zodat Cleartix je endpoint verwittigt wanneer er iets gebeurt, bijvoorbeeld:

• Een verkocht ticket
• Een ingecheckte deelnemer
• Een terugbetaalde bestelling

Wanneer de gebeurtenis zich voordoet, stuurt Cleartix een verzoek naar je URL. Leveringen zijn ondertekend, zodat je kunt verifiëren dat ze echt van Cleartix komen, en ze worden opnieuw geprobeerd als je endpoint tijdelijk onbereikbaar is — zo gaat een korte storing geen gebeurtenis verloren.

Webhook-payloads

Elke webhook is een HTTP POST waarvan de JSON-body steeds dezelfde envelope gebruikt — alleen event en data verschillen:

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

Bij elk verzoek horen twee headers:

• X-ClearTix-Signature — sha256= gevolgd door de HMAC-SHA256 van de ruwe request-body, met de ondertekeningssleutel van je endpoint. Verifieer dit voor je een payload vertrouwt.
• X-ClearTix-Event — het event-type, bv. ticket.sold.

Het data-object hangt af van het event. Elk event hieronder toont een voorbeeld-data en het bijbehorende JSON Schema.

ticket.sold — ticket gekocht en betaald

{ "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 — deelnemer ingecheckt op 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 terugbetaald

{ "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 bevestigd (inclusief gratis)

{ "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 gepubliceerd en 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" }
  }
}

Houd sleutels veilig

Een API-sleutel handelt in naam van je organisatie, dus behandel hem als een wachtwoord:

1. Zet hem nooit in versiebeheer en deel hem niet publiek.
2. Gebruik waar mogelijk een aparte sleutel per integratie.
3. Roteer een sleutel meteen als hij uitlekt, en verwijder sleutels die je niet meer gebruikt.