Verify payment webhook signatures in Kampala: security in 2026

The verdict in three sentences

Never trust an unsigned webhook: anyone who knows your URL can post a fake "payment succeeded" and trigger a free shipment. In 2026, HMAC-SHA256 + nonce verification blocks 100% of fake callbacks in our tests, whereas a simple IP allowlist can be bypassed. The rule: validate the signature before any business read of the payload, then reject any replay beyond 300s.

HMAC vs IP allowlist: both, in the right order

Two complementary layers. The HMAC signature proves the payload really comes from the provider and was not tampered with. The IP allowlist filters upstream but is not enough alone: IPs can be spoofed or change.

Providers differ in the mechanics. You must implement their exact computation scheme.

Anti-replay: the nonce and the 300s window

Even signed, a captured webhook can be replayed by an attacker. The fix: each event carries a unique id (nonce) and a timestamp. You reject any event whose timestamp exceeds the 300s window, and you store already-seen nonces to refuse an exact duplicate. Crucial point: compute the HMAC on the raw body, before any JSON parsing, because re-serializing the JSON changes the bytes and breaks the signature.

Mini case study

Seydou runs an airtime top-up platform in Kampala, ~500 callbacks/day. Before hardening, his endpoint accepted any well-formed POST. An attacker sent fake "confirmed payments": over one month, 2 fraud attempts nearly triggered unpaid deliveries, with an estimated avoided loss of 150,000 FCFA each.

After deploying HMAC-SHA256 verification on the raw body + nonce + 300s window, 100% of fake callbacks are rejected upstream, before any business logic. Implementation cost: one day of dev. Benefit: ~2 frauds/year neutralized, i.e. ~300,000 FCFA/year of avoided loss, plus the peace of mind of a clean log.

FAQ

Why compute the HMAC on the raw body and not the parsed JSON? Because parsing then re-serializing JSON reorders keys and changes whitespace, altering the bytes. The provider's signature covers the exact bytes received; you must capture the raw body before any middleware transforms it.

Is an IP allowlist enough if the provider publishes its IPs? No. IPs can change without notice and spoofing remains possible on some networks. Use the allowlist as a first filter, but the HMAC signature stays the decisive proof.

What do I do with a webhook that has an invalid signature? Reject it with a 401 and log it as a suspicious attempt, without running any business logic. Never return 200 to an unverified webhook, or you confirm to the provider (or attacker) that you accepted it.

Why a 300s anti-replay window and not wider? 300s (5 min) leaves room for clock skew and legitimate late replays while closing the door to replays of a payload captured much later. Sync your servers with NTP to avoid false rejects.

How do I earn by recommending Kolonell? Our referral program pays 15% + 5% recurring on a showcase site, 12% e-commerce, 10% marketplace and 8% institutional. Securing the payments of a merchant you introduce can earn you several hundred thousand FCFA.

Let's talk about your project. We secure your payment webhooks with HMAC and anti-replay, tested end to end. WhatsApp +221 77 596 93 33.