Developer security
Webhook signature verification for crypto payments
Webhook signature verification proves an inbound callback was issued with knowledge of your shared secret over the exact bytes received. For crypto payment infrastructure, it is the gate between public HTTP endpoints and ledger or order mutation.
Technical alignment: Discuss integration · Explore operational model
01
Operational overview
Verification is not a cosmetic header check. It is the control-plane boundary that keeps forged JSON from becoming paid state.
Operations teams should monitor signature failure rates alongside lifecycle metrics—spikes often precede integration regressions or rotation incidents.
Kobbopay shares environment-specific signing contracts after merchant approval; public pages document patterns only.
02
Raw-body verification workflow
Read the raw request body before JSON parsing. Compute expected signature with the documented algorithm and secret.
Use constant-time comparison after enforcing equal buffer lengths. Reject missing or malformed signature headers early.
Keep verification middleware separate from business logic for narrower security review.
03
Rail-agnostic patterns
Signing contracts apply across rails; event catalogs and confirmation semantics may differ per asset and network.
Document per-event mappings in your integration spec so finance can audit state transitions.
Never verify webhooks in browsers or ship webhook secrets to client applications.
04
Idempotency, replay, and ordering
Treat delivery as at-least-once. Idempotency keys on stable payment identifiers prevent duplicate side effects.
Replay windows bound how long verified events remain actionable—especially during secret rotation.
Out-of-order events need state machines that no-op safely or buffer—see webhook replay handling guide.
05
Logs, rotation, and monitoring
Log verification outcomes without secrets or full signed payloads in shared systems.
Rotate webhook secrets on compromise with dual-running verifiers during cutover.
Crypto webhook security page complements this page with broader control-plane framing.
- 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
- Reviewed merchant onboarding
- Server-side API keys only
- Signed webhook verification on raw bytes
- Explicit lifecycle states
- Operational reconciliation model
- No client-side secrets
If this model matches your B2B program, align engineering and treasury on lifecycle semantics, complete reviewed merchant onboarding preparation, run webhook verification tests in the first environment you receive, then submit a structured access request with required rails and use case context.
Frequently asked questions
- Should verification happen before JSON parsing?
- Yes. Parsing first can change bytes used for signing. Verify on the raw body received.
- Is a 200 OK response proof of business completion?
- No. It acknowledges delivery. Durable processing and idempotency must precede irreversible side effects.
- Where are secrets stored?
- Server-side secret management only—never in front-end bundles or public repositories.
- What if our framework auto-parses JSON?
- Use a raw-body capture route or framework hooks that preserve the original buffer—document the approach for audits.