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

​
Correctness

  • Idempotency: process by payment / subscription / invoice id; retries and replays will re-send the same business event
  • 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