CLI Webhooks

Manage webhook endpoints and listen for incoming events locally during development.

Manage Endpoints

List endpoints

ikw webhooks list

Inspect an endpoint

ikw webhooks inspect we_abc123

Create an endpoint

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

The create output shows the whsec_... secret once. Copy it immediately into your server-side secret manager.

A registered endpoint URL must be an absolute HTTP(S) URL. Local URLs (localhost, 127.0.0.1) and private IP ranges are rejected to prevent internal access. For local development, use the relay command: ikw listen --forward-to http://localhost:4242/webhooks.

Update an endpoint

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

Rotate signing secret

ikw webhooks rotate-secret we_abc123

After rotation, future deliveries are signed with the new secret. Update your server environment variable, for example:

export IKW_WEBHOOK_SECRET=whsec_your_new_signing_secret

Local Webhook Listener

The webhooks listen command starts a local HTTP server that receives webhook events — perfect for development and testing.

Basic usage

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	Default	Description
--port <n>	4242	Local port to listen on
--path <path>	/webhooks	URL path to listen on
--secret <secret>		Webhook signing secret (or set IKW_WEBHOOK_SECRET env var)
--tolerance-seconds <n>	300	Timestamp tolerance for signature verification
--print-headers	false	Print request headers

With signature verification

ikw webhooks listen --secret whsec_your_signing_secret

Or via environment variable:

export IKW_WEBHOOK_SECRET=whsec_your_signing_secret
ikw webhooks listen

JSON output for scripting

ikw webhooks listen --json

Each received event is printed as a JSON object:

{
  "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" }
  }
}

With a tunnel (ngrok)

To receive real webhooks from Ikawaari during development:

# Terminal 1: Start the listener
ikw webhooks listen --port 4242

# Terminal 2: Start ngrok
ngrok http 4242

Then set your webhook endpoint URL in the dashboard to https://your-ngrok-url.ngrok.io/webhooks.

Signature Verification

The listener automatically verifies the Ikawaari-Signature header using HMAC-SHA256:

Status	Meaning
signature_verified: true	Signature is valid
missing_signature_header	No signature header present
missing_secret	No secret configured
timestamp_out_of_tolerance	Event timestamp too old (replay protection)
signature_mismatch	Signature doesn't match