Qu'est-ce que l'idempotence et comment gérer les webhooks en double ?

Une connexion interrompue peut vous laisser dans l'incertitude quant au succès d'une requête d'envoi. Un accusé de réception perdu peut aussi amener un expéditeur de webhooks à livrer un événement que votre application a déjà stocké.

Ces défaillances surviennent dans des directions opposées. Bird peut reconnaître une requête API répétée grâce à une clé que vous fournissez. Votre récepteur de webhooks a besoin de son propre enregistrement des événements acceptés.

Comment réessayer un envoi en toute sécurité ?

Réutilisez le même en-tête Idempotency-Key pour chaque tentative d'une opération logique API.

Vous choisissez la clé, jusqu'à 255 caractères, et la conservez entre les tentatives. Une valeur stable comme welcome-user/usr_abc123 peut identifier une opération de message de bienvenue après le redémarrage de votre processus.

L'en-tête s'applique aux requêtes mutantes telles que POST, PATCH et DELETE. Une requête sans clé est traitée sans cette déduplication. GET ignore l'en-tête car la lecture de la ressource est déjà sûre à répéter.

Bird renvoie la réponse stockée pour une requête complétée correspondante, y compris son statut et son corps d'origine. La réponse contient Idempotency-Replay: true, ce qui vous permet d'identifier cette réutilisation dans vos logs.

Le guide d'idempotence documente une fenêtre par défaut de trois heures pour la réponse complétée. Une nouvelle tentative après son expiration peut s'exécuter comme une nouvelle opération. Ne comptez pas sur cette clé de façon permanente pour empêcher les envois en double.

Les SDK Bird génèrent une clé pour une mutation et la réutilisent lors de leurs tentatives internes. Le Bird CLI génère aussi une clé pour une requête mutante lorsqu'aucune n'est présente. Définissez --idempotency-key explicitement quand des invocations de commandes distinctes doivent partager la même opération.

Pour la soumission SMTP, utilisez l'en-tête de message X-Bird-Idempotency-Key. Cela permet à une soumission réessayée d'identifier la même opération.

Que se passe-t-il si je réutilise une clé incorrectement ?

Bird rejette une utilisation conflictuelle de clé au lieu de renvoyer une réponse pour une opération différente.

La comparaison inclut la méthode, l'endpoint, les paramètres de chemin, la chaîne de requête et le corps. Pour JSON, modifier les espaces modifie l'identité de la requête : conservez le corps original lors des nouvelles tentatives.

Le verrou sur une opération inachevée expire dans les trente secondes. Cette limite permet à une autre requête de poursuivre après une opération abandonnée. Elle n'établit pas si un effet de bord s'est déjà produit.

Bird ne stocke pas une réponse 5xx pour la rejouer. Réessayez une erreur serveur ou un délai d'attente avec la même clé afin qu'un succès enregistré puisse encore être réutilisé.

Un rejet de validation ou de règle métier libère la clé. Vous pouvez corriger cette requête rejetée et réessayer sous la même clé, car aucune réponse complétée n'a été conservée.

Pourquoi est-ce que je reçois le même webhook deux fois ?

Bird peut réessayer un événement que votre récepteur a déjà stocké s'il ne reçoit pas de réponse positive.

Un récepteur peut stocker un événement juste avant que sa connexion ne se coupe. Bird ne voit aucun accusé de réception positif et réessaie, même si le récepteur possède déjà l'événement.

Chaque nouvelle tentative conserve le même en-tête webhook-id, qui identifie l'événement. Un renvoi d'une livraison manquée conserve aussi cet identifiant, de sorte que les deux peuvent être reconnus comme le même événement.

Comment rendre mon gestionnaire idempotent ?

Stockez chaque webhook-id sous une contrainte d'unicité en base de données avant de planifier le travail de l'événement.

Vérifier l'existence d'une ligne avant d'insérer laisse une condition de concurrence : deux requêtes simultanées peuvent toutes deux ne voir aucune ligne. Laissez la base de données rejeter les identifiants en double.

Stockez l'identifiant et la tâche dans la même transaction. Cela empêche qu'un identifiant soit enregistré sans aucun travail mis en file d'attente.

1. Vérifiez la requête, puis insérez son identifiant et sa tâche dans la même transaction.
2. Renvoyez 2xx après la validation de cette transaction, afin que Bird puisse arrêter ses nouvelles tentatives.
3. Traitez la tâche stockée dans un worker capable de répéter ses propres actions en toute sécurité.

Pour un identifiant en double déjà validé, renvoyez un succès sans créer une autre tâche. Pour une transaction échouée, renvoyez une erreur afin que Bird réessaie.

Gardez le travail lent hors du récepteur, car l'attente peut provoquer un délai d'expiration de la requête. Un worker peut réessayer pour des raisons sans rapport avec la livraison de webhooks : protéger uniquement le récepteur est insuffisant.

Les événements peuvent aussi arriver dans le désordre. Comparez les horodatages d'événements dans timestamp avant d'écraser un état plus récent. Nouvelles tentatives de webhooks échoués inclut l'exemple de coût partiel.

Sur quoi ne dois-je pas compter ?

Ne supposez pas que la déduplication des requêtes rend les effets de bord en double impossibles.

Si le magasin de déduplication de Bird est indisponible, les requêtes sont traitées sans lui. Conservez une protection au niveau métier lorsque la répétition d'une action serait nuisible.

De même, webhook-id distingue les livraisons répétées d'un même événement. Des événements distincts ont des identifiants distincts. Votre application décide toujours si ces événements justifient de répéter la même action.

Idempotence documente le comportement de nouvelle tentative de API. Webhooks couvre les garanties de livraison distinctes que votre récepteur gère.