Skip to main content

Webhooks

Webhooks notify your application in real-time when events occur in your Ikawaari account — payments, refunds, subscription changes, and more.

How Webhooks Work​

  1. You register a webhook endpoint URL in the dashboard or via API
  2. Ikawaari generates a whsec_... signing secret for that endpoint and environment
  3. When an event occurs, Ikawaari sends an HTTP POST to your URL
  4. Your server verifies the signature, processes the event, and returns a 200 response
  5. If delivery fails, Ikawaari retries with exponential backoff

Set Up a Webhook​

From the Dashboard​

Go to Developers → Webhooks and click Add endpoint.

After creation or rotation, the dashboard shows the whsec_... signing secret once. Copy it immediately and store it server-side. List and detail views only show the last characters afterwards.

Registration checks that the URL is an absolute HTTP(S) URL and does not point to localhost, .localhost, a loopback IP, or a private IP range. Ikawaari does not contact your server during endpoint creation: use the Test action or the CLI to verify connectivity.

Via 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"
    ]
  }'

The create response includes the full secret:

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

Manage the webhook secret​

The webhook secret is not an API key. An API key authenticates your server when it calls Ikawaari; the webhook secret lets your server verify that an incoming webhook was sent by Ikawaari.

  • Never store whsec_... in a mobile app or frontend.
  • If the secret is lost or exposed, rotate it from the dashboard or with ikw webhooks rotate-secret <id>.
  • The new secret signs future deliveries immediately.
  • Sandbox and live use separate endpoints and secrets.

Rotate the secret​

In the dashboard, open Developers → Webhooks, then use Rotate secret on the endpoint. The confirmation shows the new secret once.

Via API:

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

Response:

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

Update your merchant backend immediately after rotation. If your backend supports a transition window, temporarily accept both the old and new secret, then remove the old one.

Accepted URLs​

CaseAcceptedNotes
https://example.com/webhooks/ikawaariYesRecommended in sandbox and required in live
http://example.com/webhooks/ikawaariYes in sandboxAvoid outside testing; use HTTPS in production
http://localhost:4242/webhooksNo for a registered endpointUse ikw listen --forward-to http://localhost:4242/webhooks
http://127.0.0.1:4242/webhooksNoBlocked to prevent internal access
http://192.168.1.10/webhooksNoPrivate IP ranges are blocked

Testing an endpoint can fail if DNS, TLS, firewall rules, or your merchant server are not reachable. In that case, the endpoint can still be configured, but real deliveries will fail until connectivity is fixed.

Webhook Payload​

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

Retry Policy​

AttemptDelay
1st retry5 minutes
2nd retry30 minutes
3rd retry2 hours
4th retry8 hours
5th retry24 hours

After 5 failed attempts, the endpoint is marked as failing and you'll receive an email notification.

Next Steps​