Skip to main content

Security

  • Always Verify Webhook Signatures before business logic
  • Reject stale timestamps
  • Check org_id so partner/metadata edge cases cannot cross orgs
  • Serve only over HTTPS; do not log full headers if they include secrets from your own reverse proxies
  • Alert on Account.Created, Account.Updated, and Account.Disabled when the account is not a change you just made. Verify the signature first. Confirm org.id is yours. For a crypto account, compare address with the address you stored for that account id, and hold payouts to the new address until someone confirms it. For a bank account, address is empty and the account number is not on the payload. Hold payouts to that account id until someone confirms the bank details. See Event Types

Correctness

  • Idempotency: process by payment / subscription / invoice id; retries and replays will re-send the same business event
  • Fulfil a payment only when event is Payment.Updated and status is Succeeded. The same payment can emit earlier Payment.Updated events with status: RequiresAction, a growing paid_amount, and proxy_wallet (address, chain_id, token_address) — persist those for reconciliation, do not mark the order paid
  • Prefer updating state machines (paid, active) rather than incrementing counters without keys
  • Persist the raw event id when available for audit

Performance

  • Return 2xx after durable write (database commit or queue enqueue)
  • Do slow work asynchronously after acknowledging, but ensure crash recovery from persisted events
  • Keep response under a few seconds to avoid timeouts marking deliveries failed

Configuration

  • Keep webhook URL and public key in sync across environments
  • Rotate keys deliberately; dual-run verification during rotations if possible
  • Distinguish request signing secrets from webhook RSA keys

Observability

  • Monitor non-2xx rates at your edge
  • Review event history weekly during early integration
  • Alert when failed_count grows

Testing

  1. Point webhook URL at a tunnel to local
  2. Create a small paylink payment or use test tools
  3. Confirm signature verification passes with dashboard public key
  4. Force a handler error, confirm failed status, Retry, confirm success