API et webhooks

Pour les développeurs sur le plan Pro, Cleartix propose une API REST et des webhooks afin de relier la billetterie à vos propres systèmes.

Clés API

Créez des clés API sous Settings pour utiliser l'API REST de Cleartix. Avec une clé, vous pouvez lire vos données depuis votre code ou vos outils — vos événements, commandes et participants — pour alimenter des tableaux de bord, synchroniser un CRM ou bâtir un rapport sur mesure.

Webhooks

Plutôt que d'interroger l'API, enregistrez des webhooks pour que Cleartix notifie votre point de terminaison quand un événement se produit, par exemple :

• Un billet vendu
• Un participant enregistré
• Une commande remboursée

Lorsque l'événement survient, Cleartix envoie une requête à votre URL. Les livraisons sont signées, ce qui vous permet de vérifier qu'elles viennent bien de Cleartix, et elles sont réessayées si votre point de terminaison est momentanément indisponible — une brève panne ne perd donc aucun événement.

Charges utiles des webhooks

Chaque webhook est une requête HTTP POST dont le corps JSON utilise toujours la même enveloppe — seuls event et data changent :

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

Deux en-têtes accompagnent chaque requête :

• X-ClearTix-Signature — sha256= suivi du HMAC-SHA256 du corps brut de la requête, avec le secret de signature de votre point de terminaison. Vérifiez-le avant de faire confiance à une charge utile.
• X-ClearTix-Event — le type d'événement, p. ex. ticket.sold.

L'objet data dépend de l'événement. Chaque événement ci-dessous montre un exemple de data et son schéma JSON.

ticket.sold — billet acheté et payé

{ "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 — participant enregistré à l'événement

{ "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 — billet remboursé

{ "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 — commande confirmée (y compris gratuite)

{ "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 — événement publié et en ligne

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

Gardez les clés en sécurité

Une clé API agit au nom de votre organisation : traitez-la comme un mot de passe.

1. Ne la mettez jamais dans un gestionnaire de versions et ne la partagez pas publiquement.
2. Utilisez si possible une clé distincte par intégration.
3. Renouvelez une clé immédiatement en cas de fuite, et supprimez celles que vous n'utilisez plus.