Webhooks

Les webhooks reçoivent des événements en temps réel par HTTP POST sur une URL que vous configurez. Les mêmes événements sont aussi disponibles via le SSE. Les webhooks sont configurés par organisation : chaque organisation a ses propres webhooks.

GestionCopier le lien vers cette section

Consultez la spécification OpenAPI pour les schémas complets de requête et de réponse.

Créer un webhookCopier le lien vers cette section

POST /api/orgs/org_abc123/webhooks
Content-Type: application/json
x-api-key: tkn_xxx

{
  "url": "https://jouw-server.com/webhooks/tillor",
  "subscribedEventKeys": ["invoice:created", "invoice:paid", "customer:updated"],
  "enabled": true
}

• url - endpoint HTTPS qui accepte les requêtes POST
• subscribedEventKeys - tableau de clés d'événements ou ["*"] pour tous les événements. La liste complète se trouve dans Tillor sous Menu du profil → Développeurs, à Ajouter un webhook → Événements abonnés.

Quelques événements sont si fréquents que vous ne pouvez pas les choisir et qu'ils n'arrivent pas non plus via *, comme l'état physique des barrières, la saisie dans la boîte de réception, les journaux du contrôleur et la présence de véhicules. Ils ne figurent pas dans la liste ci-dessous. Les événements que vous pouvez choisir dépendent aussi de vos permissions.

• enabled - true pour activer la livraison

Vous ne pouvez choisir que les événements pour lesquels votre membre de l'organisation a la permission correspondante (par ex. les transactions bancaires pour bankAccountTransaction:*). Le joker * n'est disponible que pour les membres ayant un accès complet (*). En cas de combinaison invalide, l'API renvoie un message d'erreur. Un webhook transmet le payload complet, avec les données liées (comme le client d'une réservation). Vous devez donc aussi avoir le droit de lire ces domaines pour créer un webhook, modifier l'URL ou les événements, ou le réactiver.

Payload du webhookCopier le lien vers cette section

Chaque livraison de webhook est un POST avec :

En-têtes :

• Content-Type: application/json
• X-Webhook-Event-ID - ID unique et stable de cette livraison logique (même valeur lors des nouvelles tentatives)
• X-Webhook-Signature - signature HMAC-SHA256 du corps, au format sha256=<hex> (voir Vérifier la signature)

Corps :

{
  "event": "invoice:created",
  "data": {},
  "timestamp": 1735689600000,
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "triggeredBy": {
    "id": "usr_63x8jp68is",
    "name": "Niels"
  }
}

Consultez les exemples pour des payloads complets.

Vérifier la signatureCopier le lien vers cette section

Chaque webhook possède son propre secret de signature (64 caractères hexadécimaux, visible dans le tableau des webhooks via Afficher le secret de signature sur Menu du profil → Développeurs). Tillor signe chaque POST avec ce secret pour que vous puissiez vérifier que la requête vient bien de Tillor et que le corps n'a pas été modifié.

Comment Tillor signe :

1. Calculez HMAC-SHA256(signingSecret, raw_request_body) (hex en minuscules).
2. Envoyez-le sous la forme X-Webhook-Signature: sha256=<hex>.

Comment vous vérifiez :

1. Lisez le corps brut de la requête (avant l'analyse JSON, sinon le hash ne correspond pas).
2. Calculez vous-même HMAC-SHA256(signingSecret, raw_body) en hex.
3. Comparez avec la valeur après sha256= de l'en-tête X-Webhook-Signature à l'aide d'une comparaison en temps constant.

import crypto from "node:crypto";

function verifyTillorWebhook(rawBody, headerSignature, signingSecret) {
  const expected = crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
  const received = headerSignature.replace(/^sha256=/, "");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Comportement de livraison et nouvelles tentativesCopier le lien vers cette section

• Répondez avec un statut 2xx pour confirmer la réussite.
• Si une livraison échoue (statut non 2xx, erreur réseau ou cible bloquée), Tillor réessaie automatiquement avec des intervalles de plus en plus longs. Chaque tentative réutilise le même payload, la même signature et le même ID d'événement (idempotent).

• Si l'une des tentatives réussit (2xx) → la livraison est terminée.
• Si la tentative 10 (après 24 h) échoue aussi → la livraison est définitivement marquée comme échouée et n'est plus réessayée.
• Si le webhook est entre-temps désactivé, Tillor arrête les nouvelles tentatives.

Notifications en cas d'échecs persistantsCopier le lien vers cette section

Si les livraisons vers un endpoint de webhook continuent d'échouer, Tillor envoie au maximum deux notifications par incident (par endpoint) :

1. Après 5 minutes d'échecs persistants - e-mail à l'adresse e-mail de l'organisation (supportEmail, sinon email) et aux membres de l'organisation autorisés à modifier les paramètres de l'organisation, plus une notification push (si activée) pour ces membres. L'e-mail indique depuis quand les livraisons échouent. Les dates de l'e-mail utilisent le fuseau horaire défini sous Paramètres > Général (par défaut Europe/Brussels).
2. En cas d'échec définitif - les mêmes destinataires reçoivent une notification lorsque le premier événement de cet incident est marqué comme définitivement échoué après toutes les tentatives.

Vous ne recevez pas de notification par événement échoué. Dès que toutes les livraisons échouées d'un endpoint sont résolues (livrées avec succès), un nouvel incident repart avec les mêmes règles.

Sur Menu du profil → Développeurs, le tableau des webhooks affiche pour chaque endpoint un état de livraison compact (nombre en attente de nouvelle tentative et définitivement échoués). Cliquez sur l'icône ℹ pour les détails, y compris le message d'erreur complet et le payload de la tentative la plus récente.

• Réessayer les livraisons échouées (↻) : uniquement les livraisons définitivement échouées de ce webhook.
• Forcer la nouvelle tentative (⚡) : toutes les livraisons en attente et définitivement échouées de ce webhook, quels que soient les délais planifiés. Tillor lance cela en arrière-plan afin que les grandes files d'attente (par ex. des milliers d'événements) soient traitées en toute sécurité.
• Forcer tout en haut à droite, à côté de Ajouter un webhook : la même chose pour tous les webhooks activés de l'organisation.

Types d'événementsCopier le lien vers cette section

Les clés d'événements utilisent le format entity:action ou entity:subresource:action. La liste complète, avec la permission par événement et un exemple de payload, se trouve dans l'index des événements. Cette page est générée à partir du code et est donc toujours complète. Les mêmes clés figurent dans Tillor sous Menu du profil → Développeurs, à Ajouter un webhook → Événements abonnés.

Webhooks ou SSECopier le lien vers cette section

Voir aussiCopier le lien vers cette section

• OpenAPI - spécification complète de l'API
• API HTTP - API REST et clés API
• SSE - mêmes événements via Server-Sent Events
• Automatisations - envoyer vos propres messages depuis une automatisation