Should verification happen before or after JSON parsing?

Before. Parsing first can change bytes used for signing. Verify on the raw body your framework received.

Are webhooks sufficient proof of settlement?

No. They are control-plane signals. Finance posting may require additional confirmation depth per policy.

How do we handle retries?

Design idempotent consumers keyed on stable identifiers. Treat delivery as at-least-once.

Where is the signing contract documented?

Public guides and /docs describe patterns; environment-specific contracts are provided after merchant approval.

Crypto webhook security

Operational overview

Webhook security failures show up as fraudulent paid states, duplicate fulfillments, and reconciliation drift—not only as obvious intrusion alerts.

B2B infrastructure should document signing contracts, retry semantics, and idempotency expectations where integrators can cite them during security review.

Kobbopay publishes guides, references, and journal research on verification and replay—environment-specific secrets and algorithms are shared after merchant approval.

Integration concepts

Capture the raw request body before parsing JSON. Compute the expected signature with the documented algorithm and compare using constant-time approaches after enforcing equal buffer lengths.

Reject forgeries with 401 responses without echoing secrets in logs. Parse and mutate state only after verification succeeds.

Separate verification middleware from business logic so audits have a narrow surface.

Return 2xx only when your system can safely deduplicate retries—HTTP success acknowledges delivery, not necessarily completed business processing.

Rail-agnostic control plane

Webhook security patterns apply across configured rails; event catalogs and confirmation timing may differ per asset and network.

Do not assume one handler fits every event type—document mappings per rail where behavior diverges.

Secret rotation requires dual-running verifiers or staged cutover plans to avoid dropped events during rotation windows.

Webhooks and reconciliation trust

Verified webhooks feed provider-plane truth in three-plane reconciliation—they do not automatically satisfy finance-plane posting rules.

Matchers should tolerate timing skew between webhook delivery, API reads, and chain confirmation—exceptions belong in queues with owners.

Evidence for audits includes delivery logs, signature failure rates, and idempotency decisions—not only successful 2xx counts.

Hardening checklist (public patterns)

Store webhook secrets server-side only; rotate on compromise; never verify in browsers.

Implement replay windows and ordering policies where your deployment requires them—see webhook replay handling guide and replay controls journal article.

Monitor signature errors and delivery failures alongside payment lifecycle metrics—see observability page for operational expectations.

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.

Request access Read integration docs

Frequently asked questions

Should verification happen before or after JSON parsing?: Before. Parsing first can change bytes used for signing. Verify on the raw body your framework received.
Are webhooks sufficient proof of settlement?: No. They are control-plane signals. Finance posting may require additional confirmation depth per policy.
How do we handle retries?: Design idempotent consumers keyed on stable identifiers. Treat delivery as at-least-once.
Where is the signing contract documented?: Public guides and /docs describe patterns; environment-specific contracts are provided after merchant approval.