Skip to main content

Webhooks

Purpose: Configure event-driven notification deliveries to external systems via webhooks for automation, observability, and integration.

Register Webhook​

  • Step 1: Register endpoint URL and a secret for signature verification.
  • Step 2: Select event types to subscribe to (e.g., user.created, user.deleted, invoice.paid).
  • Step 3: Test delivery and verify signature validation on consumer side.

Inspect & Retry Deliveries​

  • Use delivery logs to inspect failures; provide a manual retry on transient errors.
  • Ensure idempotency design on consumer side to handle duplicate deliveries.

Security & Best Practices​

  • Always require TLS and verify certificates (no plain HTTP).
  • Use signed payloads with secret verification (HMAC) and include timestamp to guard replay.
  • Implement retry/backoff and dead-lettering for persistent failures.

Troubleshooting​

  • 4xx responses: often due to wrong URL or authentication; check consumer logs.
  • 5xx responses: consumer side failure - verify capacity and request formats.

Operational Checklist​

  • Rotate webhook secrets periodically and notify consumers in advance.
  • Monitor delivery failure rate and create alerts for unusual spikes.