Guide
Signed webhook verification
Webhooks are how event-driven systems stay consistent: they are also a favorite attack surface if you parse before you verify.
Definitions: Signed webhook · Webhook secret · Idempotency
Conceptual operational diagram for this guide. Not live merchant data or metrics.
01
What is signed webhook verification?
It is the practice of authenticating an inbound HTTP callback using a shared secret and a signature computed over the exact raw bytes received—before treating the payload as truth.
02
Why does verification matter?
Because anyone can POST JSON to a public URL. Verification ties the body to a secret only your systems and Kobbopay should possess, reducing forgery and tampering risk when implemented correctly.
03
How does verification work (conceptually)?
You read the raw body, compute an expected signature using your webhook secret, compare using a constant-time approach after enforcing equal buffer lengths, and only then parse JSON and mutate internal state.
Retries are normal: your handler must be idempotent so duplicate deliveries do not double-ship goods or double-post ledger entries.
04
Common mistakes
- Parsing JSON before verification, changing the byte sequence used for signing.
- Verifying in the browser or shipping webhook secrets to client-side code.
- Treating 2xx as “processed” before durable writes or safe queueing.
05
Security considerations
Store webhook secrets in server-side secret management, rotate on compromise, and avoid logging raw secrets or full signed payloads in shared systems.
Read: /docs#webhook-verification, /docs#retry-idempotency, Security.
- Retries are normal. Webhook delivery is at-least-once. Design consumers to tolerate duplicates and out-of-order arrivals where possible.
- Asynchronous by design. Payers, chains, and your servers operate on different clocks. UI and finance should not assume synchronous finality.
- Eventual consistency. API reads, webhooks, and portal views may briefly diverge during transitions. Reconciliation jobs exist to converge truth.
Walkthroughs: /operations