Nouvelles tentatives et ordre

Votre endpoint tombera en panne un jour ou l'autre, et Wajub fera de nouvelles tentatives. C'est la partie facile. La partie difficile, c'est qu'une nouvelle tentative exécute votre handler une seconde fois sur un événement qu'il a peut-être déjà traité, et s'il expédie une commande à chaque exécution, il l'expédie deux fois.

Cette page couvre ce que Wajub garantit, ce qu'il ne garantit pas, et la forme de handler qui résiste aux deux.

Ce que Wajub garantit

Au moins une fois, pas exactement une fois. Chaque événement atteint votre endpoint au moins une fois. Certains l'atteindront plusieurs fois. Concevoir pour une livraison exactement une fois, c'est concevoir pour quelque chose qu'aucun système de webhooks ne fournit.

Deux cas rares font plier cette promesse, et il faut connaître les deux :

• Un événement peut arriver en retard, ou avec une partie seulement de ses données. Rarement, un événement vous parvient après des événements survenus plus tard, ou avec un data qui ne contient que l'id et l'object de l'objet. Dans ce cas, lisez l'objet dans l'API.
• Les livraisons s'arrêtent tant que Wajub restreint vos webhooks, dans le cadre d'une restriction de votre compte ou de sa fermeture. Les événements sont toujours enregistrés et listés par GET /events, mais aucun n'est envoyé, ni à vos endpoints ni à wajub listen. Les événements enregistrés pendant la restriction ne sont pas envoyés quand elle est levée : lisez-les avec GET /events et rejouez ceux dont vous avez besoin avec POST /events/{id}/resend.

C'est pourquoi un rapprochement quotidien fait partie de toute intégration : ce n'est pas un filet de sécurité facultatif. Voir La page de retour n'est pas une confirmation.

Aucune garantie d'ordre. Les événements sont livrés au fur et à mesure de leur production, avec des nouvelles tentatives intercalées. Un payment.succeeded peut arriver avant le payment.processing qui l'a précédé. Ne déduisez jamais l'état d'un paiement de l'ordre d'arrivée des événements. Lisez l'état dans le corps de l'événement, ou récupérez le paiement.

Quand une livraison compte comme un échec

Une livraison réussit quand votre endpoint répond avec n'importe quel 2xx en moins de 10 secondes. Toute autre issue est un échec.

Le calendrier des nouvelles tentatives

Wajub continue d'essayer pendant 72 heures après la première tentative. Il n'y a pas de nombre fixe de tentatives. L'attente commence à 30 secondes et double après chaque échec, jusqu'à 6 heures. Chaque attente est tirée au hasard entre la moitié et la totalité de cette valeur, pour qu'un endpoint qui redémarre après une panne ne reçoive pas toutes les nouvelles tentatives au même instant.

Une fois les 72 heures écoulées, la livraison est marquée failed et Wajub s'arrête. Votre endpoint n'est pas désactivé : le prochain événement sera quand même tenté, et vous pouvez rejouer à la main celui qui a échoué depuis Konsole ou avec POST /events/{id}/resend. Si vous supprimez ou désactivez l'endpoint pendant qu'une livraison est encore retentée, les tentatives restantes sont abandonnées.

Dédupliquer : deux clés, deux significations

Chaque livraison porte les deux. Elles ne sont pas interchangeables, et choisir la mauvaise produit un bug que vous ne verrez pas avant d'ajouter un second endpoint.

id dans le corps, une valeur evt_…, identifie l'événement. Il est identique à chaque nouvelle tentative, et identique pour chaque endpoint qui reçoit cet événement.

X-Wajub-Delivery-Id dans les en-têtes, une valeur whd_…, identifie la livraison vers un endpoint. Il reste stable sur toutes les tentatives, renvoi manuel compris, et diffère pour chaque endpoint.

La forme du handler

Quatre étapes, dans cet ordre. Tout l'enjeu est dans l'ordre.

# The same event, arriving a second time after a timeout.
# Body id and delivery id are both the ones of the first attempt.
X-Wajub-Delivery-Id: whd_7Yh2MpL4tRb3nP8sZcXv
{"id":"evt_aio5DpN577tNU2vOxdmuZGhT","event":"payment.succeeded","data":{…}}

Marquez l'événement comme traité avant d'effectuer le travail, pas après. Si vous le marquez après, deux nouvelles tentatives arrivées à peu d'intervalle peuvent toutes deux passer la vérification et toutes deux s'exécuter.

Rapprocher l'événement de la requête qui l'a provoqué

Le corps contient la requête qui a produit l'événement :

request décrit l'enregistrement de l'événement, pas votre appel API. request.id vaut null, et request.idempotency_key est une valeur idem_… générée au moment où l'événement a été stocké. Aucun des deux ne vous renvoie l'en-tête Idempotency-Key que vous avez envoyé.

Associez plutôt un événement à une commande grâce à la ressource : data.reference est la reference que vous avez fournie à la création du paiement, et data.metadata est à votre disposition. Les deux survivent à chaque nouvelle tentative, car ils font partie de la ressource et non de la livraison.

api_version est la version courante de la plateforme au moment où l'événement a été enregistré, et le corps suit la forme de cette version. Fixer votre compte ou une requête sur une version plus ancienne change ce que renvoient vos appels API, jamais ce que reçoit votre endpoint.

Inspecter et rejouer

Chaque tentative est enregistrée avec son code de statut, son corps de réponse et sa latence dans Konsole. Une fois votre endpoint corrigé, vous pouvez rejouer une seule livraison, ou jusqu'à 100 livraisons échouées d'un coup, avec le payload d'origine et un en-tête fraîchement signé.

Chaque livraison rejouée est décomptée d'un quota mensuel fixé par votre offre : 5 en Pay as you go, 25 en Growth, voir Limites. POST /events/{id}/resend envoie l'événement à chaque endpoint qui ne l'a pas encore accepté.