Webhooks

Les webhooks notifient votre application en temps réel lorsque des événements surviennent dans votre compte Ikawaari — paiements, remboursements, changements d’abonnement, etc.

Fonctionnement des webhooks

1. Vous enregistrez une URL d’endpoint webhook dans le dashboard ou via l’API
2. Ikawaari génère un secret de signature whsec_... propre à cet endpoint et à cet environnement
3. Lorsqu’un événement survient, Ikawaari envoie une requête HTTP POST à votre URL
4. Votre serveur vérifie la signature, traite l’événement et renvoie une réponse 200
5. Si la livraison échoue, Ikawaari réessaie avec un backoff exponentiel

Configurer un webhook

Depuis le dashboard

Allez dans Developers → Webhooks puis cliquez sur Add endpoint.

Après création ou rotation, le dashboard affiche le secret whsec_... une seule fois. Copiez-le immédiatement et stockez-le côté serveur. Les vues de liste et de détail n’affichent ensuite que les derniers caractères du secret.

L’enregistrement vérifie que l’URL est une URL HTTP(S) absolue et qu’elle ne cible pas localhost, .localhost, une IP loopback ou une plage privée. Ikawaari ne contacte pas votre serveur au moment de la création: utilisez l’action Tester ou le CLI pour vérifier la connectivité.

Via l’API

curl -X POST https://api.ikawaari.com/api/v1/webhook-endpoints \
  -H "Authorization: Bearer ik_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/ikawaari",
    "enabled_events": [
      "payment_intent.succeeded",
      "payment_intent.payment_failed",
      "payout.failed"
    ]
  }'

La réponse de création contient le secret complet:

{
  "id": "we_abc123",
  "url": "https://yoursite.com/webhooks/ikawaari",
  "enabled_events": ["payment_intent.succeeded"],
  "secret": "whsec_...",
  "secret_last4": "7k9p",
  "secret_created_at": "2026-07-07T15:40:00Z",
  "has_previous_secret": false,
  "rotation_recommended": false
}

Gérer le secret webhook

Le secret webhook n’est pas une clé API. Une clé API authentifie votre serveur lorsqu’il appelle Ikawaari; le secret webhook permet à votre serveur de vérifier qu’un webhook reçu provient bien d’Ikawaari.

• Ne stockez jamais whsec_... dans une application mobile ou frontend.
• Si le secret est perdu ou exposé, faites-le tourner depuis le dashboard ou avec ikw webhooks rotate-secret <id>.
• Le nouveau secret signe immédiatement les prochaines livraisons.
• Sandbox et live utilisent des endpoints et secrets séparés.

Faire tourner le secret

Depuis le dashboard, ouvrez Developers → Webhooks, puis utilisez l’action Faire tourner le secret sur l’endpoint concerné. La confirmation affiche le nouveau secret une seule fois.

Via l’API:

curl -X POST https://api.ikawaari.com/api/v1/webhook-endpoints/we_abc123/rotate_secret \
  -H "Authorization: Bearer ik_test_your_key"

Réponse:

{
  "id": "we_abc123",
  "secret": "whsec_...",
  "secret_last4": "9m2x",
  "secret_rotated_at": "2026-07-07T15:45:00Z"
}

Mettez à jour votre backend marchand immédiatement après la rotation. Si votre backend supporte une période de transition, acceptez temporairement l’ancien et le nouveau secret, puis supprimez l’ancien.

URLs acceptées

Cas	Accepté	Notes
https://example.com/webhooks/ikawaari	Oui	Recommandé en sandbox et requis en live
http://example.com/webhooks/ikawaari	Oui en sandbox	À éviter hors test; utilisez HTTPS en production
http://localhost:4242/webhooks	Non pour un endpoint enregistré	Utilisez ikw listen --forward-to http://localhost:4242/webhooks
http://127.0.0.1:4242/webhooks	Non	Bloqué pour éviter les accès internes
http://192.168.1.10/webhooks	Non	Les plages privées sont bloquées

Le test d’un endpoint peut échouer si le DNS, TLS, firewall ou serveur marchand n’est pas accessible. Dans ce cas, l’endpoint reste configurable, mais les livraisons réelles échoueront jusqu’à correction.

Payload webhook

{
  "id": "evt_abc123",
  "type": "payment_intent.succeeded",
  "created": 1708300800,
  "data": {
    "id": "pi_xyz789",
    "object": "payment_intent",
    "amount": 10000,
    "currency": "xof",
    "status": "succeeded"
  }
}

Politique de retry

Tentative	Délai
1er retry	5 minutes
2e retry	30 minutes
3e retry	2 heures
4e retry	8 heures
5e retry	24 heures

Après 5 tentatives échouées, l’endpoint est marqué comme défaillant et vous recevez une notification par email.

Étapes suivantes

• Types d’événements — Liste complète des événements
• Vérification de signature — Vérifier l’authenticité des webhooks
• Bonnes pratiques — Gestion des webhooks prête pour la production