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

L’API est en bêta. La gestion des points de terminaison en libre-service depuis le back-office (URL, sélection des événements, secret de signature, et un journal de livraison avec relecture manuelle) est prévue mais pas encore disponible. Pour l’instant, les points de terminaison de webhook sont fournis sur demande : l’équipe Service enregistre l’URL de votre point de terminaison et les événements que vous souhaitez, et renvoie un secret de signature (whsec_…) servant à vérifier les signatures.

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.

Pas encore de déclencheur de test en libre-service

Ceci est une API en lecture seule, il n’existe donc actuellement aucun point de terminaison que vous puissiez appeler pour déclencher un webhook à la demande, ni de bouton « envoyer un événement de test ». Les événements sont émis par l’activité réelle du restaurant (une réservation créée, installée, annulée, …). Pour exercer votre gestionnaire, effectuez une action réelle dans le back-office, ou demandez à l’équipe Service d’envoyer une livraison de test.

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.