Fiabilité des webhooks
Nouvelles tentatives, idempotence, journaux de livraison et traitement sûr des doublons.
Les intégrations de production doivent supposer une livraison au moins une fois : le même événement logique peut arriver plusieurs fois. Ce guide complète Recevoir les webhooks sur le plan opérationnel.
Répondre vite, traiter en asynchrone
Les webhooks sont de simples requêtes HTTP `POST`. Dans le réponse HTTP, votre handler a un rôle étroit : vérifier la charge (signature), enregistrer ou mettre en file le minimum pour ne rien perdre, puis répondre un succès HTTP à lomi. tout de suite.
Renvoyez un 2xx promptement après vérification de la signature et persistance suffisante pour accuser réception. Le travail lourd passe par votre file d'attente. Si vous bloquez sur des API tierces, de grosses transactions SQL ou des règles séquentielles avant de répondre, vous risquez de dépasser le délai de lecture HTTP sortant de lomi. (environ quatre secondes par tentative: voir délais et relances). Viser une réponse HTTP courante nettement sous une seconde laisse une marge pour les pics et les démarrages à froid.
Traitement idempotent
Servez-vous d'un identifiant d'enveloppe d'événement stable ou d'un couple (type d'événement, identifiant métier canonique) pour détecter les doublons :
- Si l'événement est déjà appliqué, ignorez ou faites un ignorer.
- Sans stockage des identifiants traités, n'assumez pas une livraison « exactement une fois ».
Cela reflète les schémas côté serveur où les métadonnées sont fusionnées et les soldes vérifient des drapeaux déjà traités.
Nouvelles tentatives et journaux
Pour le débogage opérationnel, on commence presque toujours par ce que lomi. a observé sur le fil. Le code de réponse, un extrait du corps et les durées sont consignés dans les journaux de livraison webhook, consultables depuis le tableau de bord ou l'API Webhooks. Servez-vous-en pour :
- confirmer un code non 2xx
- analyser latence et taille du corps
- déboguer signature ou parsing
Des tentatives répétées en 401 Unauthorized (corps du type « Authentication required ») signifient souvent que votre serveur ou CDN a refusé le POST avant le code webhook, les livraisons sortantes n'incluent pas d'auth Bearer / clé API ; voir Secret de signature et Authorization.
Délais, nouvelles tentatives et erreurs client
Les sections suivantes décrivent comment lomi. livre les webhooks aujourd’hui pour vous aider à anticiper délais, relances et erreurs client non renouvelables. Le comportement produit peut évoluer ; en cas de doute, fiez-vous aux journaux de livraison et à des handlers idempotents.
Délai d'attente HTTP par tentative
Le client HTTP webhook de lomi. attend environ 4 secondes (`timeout: 4000` ms par requête) la fin de la réponse HTTP de votre serveur.
- Envoyez
200/204tout de suite après vérification de`X-Lomi-Signature`(nettement sous ~1 s), puis faites suivre la logique métier par votre file. - Au-delà de ~4 s, la tentative échoue côté lomi. (timeout) pour cette tentative (sous réserve des relances ci-dessous).
Quand lomi. relance (et quand non)
À chaque tentative échouée, lomi. classe la réponse HTTP ainsi :
| Résultat | Relances ? |
|---|---|
| 2xx | Non, livré |
Erreurs client 4xx (`400`–`499`, incl. 401 Unauthorized) | Pas d'autres tentatives pour cette livraison (« erreur client non renouvelable ») |
| 5xx et erreurs transitoires / réseau | Oui: sous plafonds et backoff |
En pratique : corrigez configuration et auth (souvent visibles en 4xx) avant d'attendre une guérison automatique, lomi. ne relance pas indéfiniment une URL mal configurée.
Plafonds de tentatives
Pour les échecs réessayables (timeouts, 5xx, pannes réseau transitoires), lomi. peut tenter la livraison jusqu'à quatre fois sur certains chemins, ou jusqu'à cinq fois lorsque la livraison est mise en file, avec backoff exponentiel (délai initial d'environ 3 à 5 secondes entre tentatives).
Vous n'avez pas à distinguer les chemins de livraison dans votre handler, traitez toujours les événements sans doublon: mais ces plafonds aident à lire les journaux après une panne.
Enveloppe JSON (`lomi_environment`)
Le champ lomi_environment reflète l'environnement de déploiement (`production`, `development`, etc.). Ce n'est pas un substitut pour distinguer trafic live et test: utilisez l'environnement de votre clé API et la configuration de vos endpoints webhook.
Vérification de signature
Utilisez les octets bruts du corps. Un JSON resérialisé peut casser le HMAC. Détails : Recevoir les webhooks et Intégration API.
Test et live
Secrets et URLs webhook sont propres à l'environnement. Faites monter vos configurations progressivement pour qu'aucun secret ou URL de test ne reçoive du trafic live.
Référence API associée
Traiter les webhooks
Les webhooks fournissent des mises à jour en temps réel sur les événements de votre compte lomi. Ce guide explique comment recevoir et traiter ces notifications en toute sécurité.
Gestion des erreurs
Lors de l’intégration avec lomi., il est essentiel de gérer les erreurs proprement afin d’offrir une expérience de paiement fluide à vos clients.