# Fiabilité des webhooks Source: https://docs.lomi.africa/build/reliability/webhook-reliability Nouvelles tentatives, idempotence, journaux de livraison et traitement sûr des doublons. *** title: Fiabilité des webhooks description: 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](/build/reliability/handling-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](#timeouts-retries-and-client-errors)). 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](/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](/build/reliability/handling-webhooks). ### Lire les journaux de livraison ```bash curl -X GET "https://api.lomi.africa/webhooks/YOUR_WEBHOOK_ID/logs?limit=10&failed=true" \ -H "X-API-Key: YOUR_API_KEY" ``` `GET /webhooks/{id}/logs` accepte `limit` (max 100), `offset`, `success` et `failed`. ### Relancer une livraison en échec ```bash curl -X POST "https://api.lomi.africa/webhooks/YOUR_WEBHOOK_ID/logs/YOUR_LOG_ID/retry" \ -H "X-API-Key: YOUR_API_KEY" ``` La relance manuelle vise une entrée de journal précise. Les relances automatiques restent plafonnées : un `4xx` est en général terminal pour cette séquence, un `5xx` ou un timeout peut être retenté. Voir [délais et relances](#timeouts-retries-and-client-errors).

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`** / **`204`** tout 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](/build/reliability/handling-webhooks) et [Intégration API](/start/first-payment). ## 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 * [API Webhooks](/build/reliability) * [Cycle de vie des paiements](/build/reliability/payment-lifecycle)