Aperçu des webhooks

Les webhooks envoient des événements vers votre serveur en temps réel, ce qui vous évite de sonder l’API. Lorsqu’un événement se produit dans un restaurant — une réservation est créée, un client est mis à jour, un avis arrive — nous envoyons une requête HTTP POST à une URL que vous contrôlez, accompagnée d’un événement JSON décrivant ce qui s’est passé.

Enregistrer un point de terminaison

Les points de terminaison de webhook sont en libre-service depuis le back-office. Un propriétaire ou copropriétaire peut les gérer dans Paramètres → Développeurs :

1. Ajoutez un point de terminaison avec son URL — une adresse HTTPS, accessible publiquement (les hôtes internes ou privés sont rejetés).
2. Choisissez les événements qu’il doit recevoir — des types d’événements individuels ou tous les événements.
3. Révélez son secret de signature (whsec_…) et stockez-le ; il sert à vérifier les signatures. Vous pouvez le faire tourner par la suite s’il est un jour exposé.

Depuis le même écran, vous pouvez activer, désactiver ou supprimer un point de terminaison, consulter un journal de livraison indiquant le statut et la réponse de chaque tentative, renvoyer une livraison passée et envoyer un événement de test. Un restaurant peut enregistrer jusqu’à 5 points de terminaison.

Chaque point de terminaison est épinglé à une version de l’API à sa création, afin que la forme de la charge utile que vous recevez reste stable.

Tester votre gestionnaire

Ceci est une API en lecture seule : aucun appel d’API ne déclenche un webhook à la demande. Les événements réels sont émis par l’activité réelle du restaurant (une réservation créée, installée, annulée, …). Pour exercer votre gestionnaire sans en attendre un, envoyez un événement de test au point de terminaison depuis Paramètres → Développeurs, ou effectuez une action réelle dans le back-office.

L’enveloppe d’événement

Chaque livraison est un objet JSON avec cette enveloppe :

{
  "id": "evt_1K8xQ2m4Vd0pErJ7sN1aZ9bQ",
  "object": "event",
  "type": "reservation.updated",
  "created": "2026-06-27T17:30:00Z",
  "livemode": true,
  "api_version": "2026-06-27",
  "data": {
    "object": { "object": "reservation", "id": "resv_…" },
    "previous_attributes": { "party_size": 2 }
  }
}

Champ	Description
id	Identifiant d’événement unique (evt_…). Utilisez-le pour dédupliquer (voir ci-dessous).
object	Toujours "event".
type	Le type d’événement, par ex. reservation.updated. Voir le catalogue des événements.
created	Le moment où l’événement a été émis — ISO-8601 en UTC (un suffixe Z). Voir la note sur les fuseaux horaires ci-dessous.
livemode	Toujours true pour les événements réels.
api_version	La version dans laquelle la charge utile est rendue (la version épinglée du point de terminaison).
data.object	Un instantané complet de la ressource concernée, dans la même forme que l’API.
data.previous_attributes	Uniquement sur reservation.updated — une table des champs modifiés vers leurs valeurs précédentes. Omis sur tout autre type d’événement.

Deux fuseaux horaires, par conception

Le created de premier niveau de l’enveloppe est en UTC (Z) — il marque l’instant où l’événement a été émis. Les champs datetime à l’intérieur de data.object (starts_at, created_at, updated_at, responded_at, …) portent en revanche le décalage UTC du restaurant (par ex. +02:00), conformément à l’API REST. Ce mélange est intentionnel : analysez chaque champ d’après son propre suffixe plutôt que de présumer un seul fuseau pour toute la charge utile.

Répondre aux événements

Renvoyez rapidement un code de statut 2xx (idéalement en quelques secondes) pour accuser réception. Effectuez le vrai travail de manière asynchrone. Toute réponse non 2xx, un délai d’expiration ou une erreur de connexion est traité comme une livraison échouée et fera l’objet d’une nouvelle tentative.

Vérifiez toujours la signature

Avant de faire confiance à une charge utile, vérifiez l’en-tête Service-Signature par rapport au secret whsec_ de votre point de terminaison. Voir Vérifier les signatures.

Sémantique de livraison

Au moins une fois, déduplication sur event.id

La livraison est au moins une fois. Le même événement peut être livré plus d’une fois (par exemple, si votre serveur est lent à accuser réception et que nous réessayons, ou après une erreur réseau transitoire). Dédupliquez sur l’id de l’événement (evt_…) : enregistrez les identifiants que vous avez traités et ignorez les répétitions. Rendez votre gestionnaire idempotent.

Aucune garantie d’ordre

Les événements ne sont pas garantis d’arriver dans l’ordre où ils se sont produits. Par exemple, vous pourriez recevoir reservation.seated avant reservation.confirmed. Ne présumez pas de l’ordre. Lorsqu’une décision dépend de l’état actuel, traitez l’événement comme un indice et récupérez la dernière version de la ressource depuis l’API, ou réconciliez à l’aide du updated_at de chaque ressource.

Nouvelles tentatives et désactivation automatique

Si une livraison échoue, nous réessayons avec un délai exponentiel sur environ 3 jours. Si toutes les tentatives échouent pendant toute cette fenêtre (le point de terminaison reste injoignable ou continue de renvoyer des erreurs), le point de terminaison est automatiquement désactivé et une alerte est levée. Vous devrez corriger le point de terminaison et le faire réactiver. Pour récupérer les événements manqués pendant qu’un point de terminaison était hors service, relisez les données avec updated_since.

Les réservations importées n’émettent pas de webhooks

Les réservations importées sont exclues

Les réservations importées depuis un autre fournisseur n’émettent pas de webhooks. Si vous vous appuyez uniquement sur les webhooks pour un restaurant qui importe également des réservations depuis un autre fournisseur, vous ne verrez pas ces réservations. Utilisez le sondage avec updated_since pour capturer les réservations importées, ou lisez-les directement via l’API.