Webhooks

Configuring your endpoint

Set your webhook URL and choose which events to subscribe to from the Merchant Portal's Webhooks page — generate a signing secret there too (shown once, like an API key), and use the page's Send Test Webhook button to confirm your endpoint is reachable before going live. The same page shows the status of your most recent delivery attempt.

Event types

The events below are the ones your integration should actually handle. A few additional names are reserved in the schema for features on the roadmap (refunds, chargebacks, scheduled sweeps) — you'll see them in the enum, but nothing emits them yet.

Payload shape

{
  "event_name": "collection.success",
  "payload": {
    "collection_id": "9b7e2c1a-...",
    "amount": "25000.00",
    "currency": "TZS"
  },
  "created_at": "2026-08-14T09:00:12Z"
}

Verifying a delivery

Every delivery is signed with your merchant's webhook secret, sent as X-Infinity-Signature: an HMAC-SHA256 hex digest of the exact raw request body. Recompute it and compare — don't trust a delivery that doesn't match, and use a constant-time comparison to avoid leaking timing information.

import hashlib
import hmac

def verify_signature(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)