Les webhooks sont la façon la plus rapide de rester synchronisé avec Nowistay. Au lieu d’interroger l’API toutes les quelques minutes pour détecter les nouvelles réservations ou les changements, vous indiquez à Nowistay l’URL où envoyer les événements, et votre service les reçoit dès qu’ils se produisent. Cet article vous montre comment créer un webhook, vérifier la signature et gérer les nouvelles tentatives.
L’API REST publique Nowistay permet à vos outils et partenaires de lire et d’écrire les données Nowistay en HTTPS. Vous vous authentifiez avec OAuth2 (authorization code + PKCE), vous obtenez un token d’accès, puis vous appelez les endpoints sous /public/v1/*. Les webhooks sont la version push : mêmes données, même format que GET /public/v1/bookings/{id}, mais c’est Nowistay qui vous les envoie dès qu’il y a un changement.
Si vous n’avez pas encore configuré OAuth, commencez par le guide principal : Utiliser l’API REST publique Nowistay. Il couvre l’enregistrement, le flux de consentement, les scopes et comment tester depuis le playground des docs.
booking.created et booking.updated.GET /public/v1/bookings/{id} : dates, canal, statut, montants, champs liés aux missions et vos paramètres personnalisés de réservation.webhooks.write. POST /public/v1/webhooks exige aussi bookings.read, car le payload est un détail de réservation complet.2xx.Réponse :
Sauvegardez tout de suite le
signingSecret. Il n’est renvoyé qu’une seule fois, à la création. Il est impossible de le récupérer plus tard depuis l’API. Si vous le perdez, supprimez le webhook et recréez-en un.
Chaque livraison est un POST HTTP sur votre URL, avec ces en-têtes :
Content-Type: application/jsonUser-Agent: Nowistay-Webhooks/1.0Nowistay-Webhook-Id: 801Nowistay-Webhook-Event-Id: evt_LkP2sxR9zV8QyW... (unique par événement)Nowistay-Webhook-Event-Type: booking.updatedNowistay-Webhook-Timestamp: 1779292800 (secondes Unix)Nowistay-Webhook-Signature: v1=3a7b...e1c (HMAC-SHA256 hex)Et un corps JSON dans ce format :
Votre endpoint doit répondre avec un statut 2xx (200 ou 204 typiquement). Tout autre statut, ou une réponse qui prend plus de 10 secondes, compte comme un échec et déclenche une nouvelle tentative.
Vérifiez toujours la signature avant de faire confiance au contenu. Sans cette vérification, n’importe qui qui devine votre URL pourrait envoyer de faux événements à votre service.
Nowistay calcule la signature ainsi :
Recalculez-la côté serveur en utilisant les en-têtes Nowistay-Webhook-Timestamp, Nowistay-Webhook-Event-Id et le corps brut exact de la requête (ne parsez pas et ne sérialisez pas le JSON avant la vérification, vous risqueriez une différence d’octets).
Vérifiez aussi que le timestamp est récent (par exemple, dans les 5 dernières minutes) pour vous protéger des attaques par rejeu.
L’objet data.booking reflète ce que renvoie GET /public/v1/bookings/{id} appelé sans le scope bookings.sensitive.read. Ça veut dire :
Quand votre outil a besoin de l’un de ces champs sensibles, allez chercher le détail de la réservation via l’API avec un token qui porte le scope bookings.sensitive.read. Le bookingId contenu dans l’enveloppe du webhook est la bonne entrée pour cet appel.
Si votre endpoint renvoie un statut autre que 2xx, dépasse le délai, ou échoue pour une raison quelconque, Nowistay ne perd pas l’événement. Une nouvelle tentative est planifiée, avec un délai qui double à chaque échec et un peu de jitter :
Cela continue jusqu’à ce que votre endpoint accepte l’événement, ou jusqu’à ce que le webhook ait échoué pendant plus de 72 heures d’affilée. À ce moment-là Nowistay met le webhook en statut disabled et arrête de lui envoyer de nouveaux événements. Les compteurs d’échec se réinitialisent dès qu’une livraison réussit, donc un incident isolé ne déclenche jamais la désactivation.
Les enregistrements de livraison sont conservés pendant 30 jours, puis nettoyés.
Un webhook désactivé peut être réactivé depuis l’API une fois que votre endpoint est de nouveau en bonne santé. Envoyez un PATCH avec status: "active" :
Nowistay ne rejoue pas les événements qui se sont produits pendant la désactivation. Si vous en avez manqué, faites un rattrapage ponctuel avec GET /public/v1/bookings et un filtre de dates, puis reprenez votre flux webhook normal.
Vous pouvez suspendre temporairement les livraisons (pendant une fenêtre de maintenance par exemple) sans perdre la configuration du webhook :
Vous pouvez aussi modifier url, la liste events ou la description dans le même appel. Changer l’URL ne change pas la clé de signature.
La réponse liste affiche les mêmes champs que la réponse de création, sans la clé de signature (elle n’est renvoyée qu’à la création).
https://user:pass@... est refusé).localhost, pas de plages d’IP privées ou réservées. Nowistay résout aussi le hostname au moment de la livraison et bloque les appels qui résolvent vers une adresse privée.id d’événement peut être redélivré après un échec. Stockez-le et ignorez-le s’il a déjà été traité.2xx immédiatement et traitez l’événement dans une tâche de fond s’il est lourd.Nowistay-Webhook-Event-Id et l’id de requête dans vos logs. Ça accélère le support.GET /public/v1/bookings/{id} après réception.https://api.nowistay.dev et validez votre vérification de signature avant de passer en production.