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, deelnemers en verkoopstatistieken per evenement (verkochte tickets, check-ins en omzet, uitgesplitst per tickettype, zonder deelnemersgegevens) — om dashboards te voeden, een CRM te synchroniseren of een eigen rapport te bouwen. Elke sleutel krijgt eigen scopes, zodat je een integratie precies de toegang geeft die ze nodig heeft — bijvoorbeeld alleen de geaggregeerde verkoopcijfers.

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" }
  }
}

Widgets via de API

Alles wat je in het dashboard met eventwidgets kunt doen, kan ook via de API. Zo kan een website-integratie — bijvoorbeeld een WordPress-plugin — widgets aanmaken en plaatsen zonder dat iemand fragmenten met de hand kopieert. Sleutels hebben de scope widgets:read nodig om widgets op te vragen en widgets:write om ze aan te maken, te wijzigen of te verwijderen.

Een widget-body gebruikt dezelfde velden als het formulier in het dashboard:

{
  "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 all_upcoming, templates (met eventTemplateIds), manual (met eventIds) of location (met locationIds); view is list of calendar. Elke widget die de API teruggeeft bevat een embed-blok met de URL van het laadscript, de iframe-URL, een kant-en-klaar snippet en de data-*-attributen die het script leest — plaats het fragment of bouw je eigen <script>/<iframe> op basis van die waarden. Omdat het fragment enkel naar het widget-ID verwijst, zijn latere wijzigingen via de API of het dashboard meteen zichtbaar op de website.

OpenAPI-specificatie

De volledige API is beschreven in een machineleesbaar OpenAPI 3.1-document op https://cleartix.io/api/v1/openapi.json. Importeer het in Postman of Swagger UI om de endpoints te verkennen, of geef het aan een clientgenerator voor je programmeertaal. Elke operatie vermeldt de vereiste scope en de exacte vorm van request en response.

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.