Comment gérer les webhooks ?

Les webhooks indiquent à votre backend qu’un événement important s’est produit après une action client ou fournisseur. Utilisez-les pour la réconciliation, la livraison, les emails, les abonnements et les mises à jour comptables.

À quoi servent les webhooks ?

Utilisez-les pour :

• Confirmer qu’un paiement est complété avant de livrer une commande.
• Savoir qu’un paiement a échoué, expiré ou été annulé.
• Suivre création, renouvellement et annulation d’abonnement.
• Réconcilier remboursements, reversements et changements d’état transaction.
• Récupérer les cas où le client ne revient jamais via la redirection navigateur.

Handler minimal sûr

Votre endpoint webhook doit :

1. Lire le corps brut de la requête.
2. Vérifier la signature avec le secret webhook.
3. Stocker l’ID d’événement ou de livraison.
4. Ignorer les doublons sans effet secondaire.
5. Relire les ressources liées via l’API quand l’état final doit être sûr.
6. Répondre rapidement avec 2xx après acceptation de l’événement.

Erreurs courantes

Que tester ?

Testez les événements réussis, échoués, dupliqués et retardés en sandbox. Vérifiez que l’état dashboard, l’état commande et la communication client sont cohérents.

Sécurité des webhooks

Pour garantir l’authenticité et l’intégrité des événements, lomi. signe chaque requête envoyée vers votre URL avec un secret propre à ce webhook.

1. En-tête de signature : chaque requête inclut l’en-tête HTTP `X-Lomi-Signature`.
2. Secret webhook : à la création d’un webhook via l’API, un `secret` (préfixe `whsec_`) est renvoyé. Conservez ce secret en lieu sûr : il ne sera plus affiché.
3. Vérification : votre URL doit recalculer un hachage `HMAC-SHA256` du corps brut de la requête avec ce secret et le comparer à la valeur de l’en-tête.

Livraison sortante : les requêtes de lomi. vers votre URL ne s’authentifient pas avec `Authorization` / `X-API-Key`, seule la signature compte. Un middleware qui impose Bearer ou clé API sur tous les POST renverra souvent `401` (détails).

Voir le guide Vérification de signature des webhooks pour des exemples d’implémentation.

Événements webhook

Lors de la création ou de la mise à jour d’un webhook, vous souscrivez à des types d’événements précis. lomi. n’envoie que ceux auxquels vous êtes abonné.

Charge utile SUBSCRIPTION_UPDATED

Les changements non terminaux utilisent une enveloppe d’événement structurée : état actuel dans object, ce qui a changé dans previous_attributes, et context optionnel pour le débogage.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "SUBSCRIPTION_UPDATED",
  "timestamp": "2026-06-11T14:30:00.000Z",
  "data": {
    "object": {
      "subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "paused",
      "price_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "cancel_at_period_end": false,
      "next_billing_date": "2026-07-01",
      "plan_name": "Pro Mensuel",
      "billing_interval": "month"
    },
    "previous_attributes": {
      "status": "active"
    },
    "context": {
      "source": "merchant_api",
      "actor": "merchant"
    }
  }
}

Réconciliez les droits d’accès à partir de data.object. Utilisez previous_attributes pour distinguer pause, changement de plan, etc. context.source vaut merchant_api, customer_portal ou cron.

(Les autres charges sont documentées sur les ressources API concernées, Transactions, Abonnements, etc.)

Les abonnements et les corps JSON utilisent des noms d’événement en SCREAMING_SNAKE_CASE (par ex. PAYMENT_SUCCEEDED). Certains outils peuvent afficher des alias avec points (par ex. payment.succeeded), utilisez les valeurs ci-dessus pour configurer vos URLs et comparer le champ event.

Pour le comportement opérationnel (nouvelles tentatives, idempotence, journaux), voir Fiabilité des webhooks.

Tester les webhooks

Vous pouvez tester les webhooks via l’API ou `curl.

Créer un webhook de test

Créez d’abord une URL vers un récepteur de test (par ex. Webhook.site ou tunnel local ngrok).

curl -X POST "https://api.lomi.africa/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "url": "YOUR_TEST_WEBHOOK_URL",
    "authorized_events": ["PAYMENT_SUCCEEDED", "test.webhook"],
    "description": "Test Endpoint"
  }'

Notez `id` et `secret` dans la réponse.

Envoyer un événement de test

Utilisez `POST /webhooks/{id}/test` pour envoyer un événement `test.webhook`.

curl -X POST "https://api.lomi.africa/webhooks/YOUR_WEBHOOK_ID/test" \
  -H "X-API-Key: YOUR_API_KEY"

Vérifiez sur le récepteur de test et validez la signature avec le secret stocké.

Journaux de livraison et nouvelles tentatives

lomi. journalise chaque tentative et expose des endpoints pour consulter les journaux et relancer manuellement les échecs.

Obtenir les journaux de livraison

URL : `GET /webhooks/{id}/logs`

Relancer une livraison

URL : `POST /webhooks/{webhook_id}/logs/{log_id}/retry`

Nouvelles tentatives automatiques : lorsque votre URL rejette une livraison (réponse non‑2xx), franchit le délai d’expiration côté lomi ou subit une panne transitoire, la plateforme enregistre l’échec et peut planifier d’autres essais, selon la sémantique HTTP et le chemin technique. Ces relances sont bornées : elles suivent des politiques de backoff exponentiel sur l’infrastructure webhook, pas une boucle infinie.

En général les erreurs client 4xx sont terminales pour la séquence automatique (corriger la configuration côté destinataire), tandis que les erreurs transitoires (5xx, timeouts, défauts réseau ponctuels) peuvent être rejouées jusqu’à un nombre borné de tentatives avec backoff exponentiel. Voir Fiabilité des webhooks: Délais et tentatives pour le timeout HTTP ≈ quatre secondes, jusqu’à quatre tentatives sur certains chemins, cinq lorsque la livraison est mise en file, et le sens de lomi_environment.

API liée

• Créer un endpoint webhook
• Lister les endpoints
• Journaux de livraison
• Traiter les webhooks
• Fiabilité des webhooks