Skip to main content

Webhooks Production Checklist

Before promoting your integration to production, review the following items. Each item links to the relevant detailed guide — if anything is missing, fix it on the linked page.

Transport channel​

Signature verification​

  • Raw body preserved (no JSON parsing before signature verification) (Verifying — Algorithm)
  • HMAC comparison uses constant time (timingSafeEqual / subtle.ConstantTimeCompare)
  • webhook-timestamp validated within ±5 minutes (Verifying — Replay protection)
  • Verification iterates over a secret array, for forward compatibility with multi-secret delivery

Idempotency / retry​

  • Dedup table operated using webhook-id (Delivery — Idempotency / duplicate handling)
  • Response within 10 seconds (offload heavy work to a queue) (Delivery — Retry policy)
  • Aside from 2xx and 409, every response code triggers retries — use explicit 4xx/5xx carefully (respond 200 or 409 for duplicate-dedup results)
  • Domain processing runs in the same transaction as the dedup insert

Security / logging​

  • Secret stored in a secret manager or environment variable; not committed to code (Overview — Secret)
  • Signatures and secrets are never logged, or are masked when logged
  • Review log retention policy — webhook bodies may contain PII
  • Alert when the 401 / 5xx response rate exceeds a threshold

Business logic​

  • Do not finalize an order from the browser result alone (do not finalize payment based on popup result / redirect params alone)
  • Once a terminal state (PAID / FAILED / EXPIRED / CANCELLED) is reached, a new payment must start with a new POST /v1/payments call
  • The payment.completed payload has no fee breakdown, so enrich via GET /v1/payments/:id if you need settlement data
  • Unknown values for failure_reason fall back to UNKNOWN
  • Do not bind business logic directly to provider values (binancepay / payletter / onchain) — drive decisions from status and amount

Operational monitoring​

  • Dashboard for receive rate, signature verification failure rate, duplicate rate, processing latency (p95)
  • Alert on webhook processing latency (e.g. p95 > 5s)
  • Alert on webhook processing failures (5xx rate > N%)
  • Track failure_reason=ONCHAIN_TIMEOUT rate (can spike during network anomalies)

Next steps​

If you run into issues or need deeper detail: