Webhooks

Les webhooks permettent à votre application de recevoir des notifications en temps réel sur ce qui se passe dans votre compte lomi. : paiements réussis, renouvellements d’abonnement, transactions en échec, etc. Au lieu d’interroger l’API en boucle, vous configurez une URL où lomi. enverra les données d’événement via des requêtes HTTP `POST`.

URL de base

https://api.lomi.africa

Authentification

Les requêtes d’API qui gèrent les webhooks exigent une clé API dans l’en-tête `X-API-Key`. Voir Authentification.

X-API-Key: your_api_key

Sécurité des webhooks

Pour garantir l’authenticité et l’intégrité des événements, lomi. signe chaque requête envoyée vers votre point de terminaison 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 point de terminaison 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.

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é.

(La structure précise des charges par type sera documentée sur la ressource concernée — 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 points de terminaison et comparer le champ event.

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

Points de terminaison de l’API

Lister les webhooks

Récupère la liste des webhooks configurés pour votre organisation.

Point de terminaison : `GET /webhooks`

Exemple de réponse (200 OK) :

{
  "data": [
    {
      "id": "wh_a1b2c3d4e5f6",
      "organization_id": "org_f6e5d4c3b2a1",
      "url": "https://example.com/webhook-receiver",
      "events": ["PAYMENT_SUCCEEDED", "SUBSCRIPTION_RENEWED"],
      "active": true,
      "created_at": "2025-04-06T12:00:00.000Z",
      "updated_at": "2025-04-06T12:00:00.000Z",
      "description": "Primary production webhook"
    }
  ]
}

Créer un webhook

Crée un nouveau point de terminaison webhook.

Point de terminaison : `POST /webhooks`

Corps de la requête :

{
  "url": "https://example.com/new-webhook-receiver",
  "authorized_events": ["PAYMENT_SUCCEEDED", "PAYMENT_FAILED"],
  "description": "Webhook for payment events"
}

• `url` (`string`, obligatoire) : URL HTTPS du point de terminaison.
• `authorized_events` (`array of strings`, obligatoire) : liste des types d’événements (voir Événements webhook).
• `description` (`string`, facultatif) : libellé descriptif.

Exemple de réponse (201 Created) :

{
  "data": {
    "id": "wh_new1b2c3d4e5f6",
    "organization_id": "org_f6e5d4c3b2a1",
    "url": "https://example.com/new-webhook-receiver",
    "events": ["PAYMENT_SUCCEEDED", "PAYMENT_FAILED"],
    "active": true,
    "created_at": "2025-04-06T14:00:00.000Z",
    "updated_at": "2025-04-06T14:00:00.000Z",
    "description": "Webhook for payment events"
  },
  "secret": "whsec_abc123def456..."
}

Obtenir un webhook

Récupère le détail d’un webhook.

Point de terminaison : `GET /webhooks/{id}`

Paramètres de chemin :

Exemple de réponse (200 OK) :

{
  "data": {
    "id": "wh_a1b2c3d4e5f6",
    "description": "Updated description"
  }
}

Mettre à jour un webhook

Met à jour un webhook existant.

Point de terminaison : `PATCH /webhooks/{id}`

Paramètres de chemin :

Corps de requête (champs à mettre à jour uniquement) :

{
  "url": "https://example.com/updated-webhook-receiver",
  "authorized_events": ["PAYMENT_SUCCEEDED"],
  "is_active": false,
  "description": "Updated description"
}

Supprimer un webhook

Supprime un webhook.

Point de terminaison : `DELETE /webhooks/{id}`

Réponse exemple (204 No Content) : aucun corps.

Tester les webhooks

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

Créer un webhook de test

Créez d’abord un point de terminaison 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

Point de terminaison : `GET /webhooks/{id}/logs`

Relancer une livraison

Point de terminaison : `POST /webhooks/{webhook_id}/logs/{log_id}/retry`

Nouvelles tentatives automatiques : lomi. relance automatiquement les livraisons en échec avec un recul exponentiel pendant environ six heures avant de marquer un échec définitif.

Bonnes pratiques

• Vérifier les signatures : vérifiez toujours `X-Lomi-Signature.
• Répondre vite : renvoyez un statut `2xx` en quelques secondes ; déportez le travail long en arrière-plan.
• Anticiper les relances : lomi peut renvoyer un événement si votre endpoint échoue ou dépasse le délai.
• Idempotence : le traitement doit tolérer les doublons.
• Protéger le secret : stockez-le via variables d’environnement ou gestionnaire de secrets.