Idempotency

You can replay any webhook at Kanall, at any time, as many times as you want. It will be processed exactly once — and every subsequent delivery will get a silent 200 OK with nothing written. This is not an accident. It is the most important reliability guarantee in the system.

Why it matters

Nomba retries webhook delivery if your endpoint returns a non-2XX response, or if Nomba's own delivery infrastructure experiences a transient failure. The same payment event can arrive at Kanall multiple times. Without an idempotency gate, you would record double ledger entries, deliver duplicate webhooks to your endpoint, and end up with a balance that reports twice the actual amount received.

How it works

Every payment event from Nomba carries a unique delivery ID. The first time Kanall sees this ID, it records the payment and posts the ledger entries. If the same event arrives again — because Nomba retried delivery — Kanall recognises the ID and returns 200 OK without writing anything. This is unconditional: the response to Nomba is always 200 OK, whether the event was new or a duplicate.

The critical guarantee is that the idempotency record and the ledger write happen together. If the ledger write fails for any reason, the idempotency record is also rolled back — meaning the next delivery of the same event is treated as new, not silently swallowed.

Replay safety

You can safely replay any webhook at any time. Kanall will process it once and return 200 OK on all subsequent deliveries.

Idempotency keys by flow

Flow	Idempotency key
Inbound VA payment (webhook)	Nomba's webhook delivery ID — stable across Nomba's own retries
Outbound transfer	merchantTxRef — generated by Kanall at settlement initiation

These are distinct flows with distinct keys. Inbound and outbound idempotency are tracked separately.