Webhooks CLI

Gérez les endpoints webhook et écoutez les événements entrants en local pendant le développement.

Gérer les endpoints

Lister les endpoints

ikw webhooks list

Inspecter un endpoint

ikw webhooks inspect we_abc123

Créer un endpoint

ikw webhooks create \
  --url https://yoursite.com/webhooks/ikawaari \
  --enabled-events payment_intent.succeeded,payment_intent.payment_failed

La sortie de création affiche le secret whsec_... une seule fois. Copiez-le immédiatement dans votre gestionnaire de secrets serveur.

L’URL d’un endpoint enregistré doit être une URL HTTP(S) absolue. Les URLs locales (localhost, 127.0.0.1) et les plages privées sont refusées pour éviter les accès internes. Pour développer en local, utilisez le relais ikw listen --forward-to http://localhost:4242/webhooks.

Mettre à jour un endpoint

ikw webhooks update we_abc123 \
  --url https://yoursite.com/webhooks/v2 \
  --enabled-events payment_intent.succeeded,payout.failed \
  --enabled true

Faire tourner le secret de signature

ikw webhooks rotate-secret we_abc123

Après rotation, les prochaines livraisons sont signées avec le nouveau secret. Mettez à jour votre variable d’environnement serveur, par exemple:

export IKW_WEBHOOK_SECRET=whsec_your_new_signing_secret

Relais local sandbox

La commande recommandée pour tester un webhook localement est ikw listen. Elle ouvre une session de relais sandbox authentifiée, se connecte au hub Ikawaari et transfère les événements vers votre serveur local. Aucun tunnel public n’est nécessaire pour les événements de test.

ikw listen --forward-to http://localhost:4242/webhooks

Puis déclenchez un événement sandbox depuis un autre terminal :

ikw trigger webhook.ping
ikw trigger payment_intent.succeeded --data '{"amount":5000,"currency":"XOF"}'

Le CLI signe chaque requête transférée avec le secret de session whsec_... et ajoute les headers Ikawaari-Signature, Ikawaari-Event-Id, Ikawaari-Event-Type et Ikawaari-Relay-Session-Id. Votre handler local peut donc utiliser la même logique de vérification que vos endpoints de production.

Options du relais

Flag	Défaut	Description
--forward-to <url>	requis	URL locale recevant les POST webhook
--events <csv>	tous	Types d’événements à relayer
--environment <environment>	sandbox	Environnement de test à utiliser
--timeout <seconds>	7200	Durée maximale de la session
--allow-non-local-forward-to	false	Autorise explicitement une URL non locale

Par défaut, le CLI refuse de relayer vers une URL non locale. Cette protection évite d’envoyer par erreur des payloads de test vers un service externe.

Listener HTTP local legacy

La commande webhooks listen démarre un serveur HTTP local qui reçoit les événements webhook — parfait pour le développement et les tests.

Utilisation de base

ikw webhooks listen

listening: http://localhost:4242/webhooks
hint: expose this port with a tunnel (ngrok/localtunnel) then set your webhook endpoint URL to /webhooks

Options

Flag	Défaut	Description
--port <n>	4242	Port local d’écoute
--path <path>	/webhooks	Chemin URL à écouter
--secret <secret>		Secret de signature webhook (ou définir la variable d’env IKW_WEBHOOK_SECRET)
--tolerance-seconds <n>	300	Tolérance temporelle pour la vérification de signature
--print-headers	false	Affiche les headers de requête

Avec vérification de signature

ikw webhooks listen --secret whsec_your_signing_secret

Ou via variable d’environnement :

export IKW_WEBHOOK_SECRET=whsec_your_signing_secret
ikw webhooks listen

Sortie JSON pour le scripting

ikw webhooks listen --json

Chaque événement reçu est affiché comme objet JSON :

{
  "received_at": "2026-02-19T10:30:00.000Z",
  "path": "/webhooks",
  "event": "payment_intent.succeeded",
  "signature_present": true,
  "signature_verified": true,
  "payload": {
    "id": "evt_abc123",
    "type": "payment_intent.succeeded",
    "data": { "id": "pi_xyz789", "amount": 5000, "currency": "xof", "status": "succeeded" }
  }
}

Avec un tunnel (ngrok)

Pour recevoir de vrais webhooks Ikawaari pendant le développement :

# Terminal 1: Démarrer le listener
ikw webhooks listen --port 4242

# Terminal 2: Démarrer ngrok
ngrok http 4242

Définissez ensuite l’URL de votre endpoint webhook dans le dashboard sur https://your-ngrok-url.ngrok.io/webhooks.

Vérification de signature

Le listener vérifie automatiquement le header Ikawaari-Signature avec HMAC-SHA256 :

Statut	Signification
signature_verified: true	La signature est valide
missing_signature_header	Aucun header de signature présent
missing_secret	Aucun secret configuré
timestamp_out_of_tolerance	Horodatage de l’événement trop ancien (protection contre le rejeu)
signature_mismatch	La signature ne correspond pas