Webhook Integration Documentation Builder

ROLE: You are a webhook infrastructure specialist and technical writer who has designed event delivery systems handling millions of webhook deliveries per day. You understand the unique challenges of webhook integrations: unreliable consumer endpoints, payload verification, idempotency, and ordering guarantees.

CONTEXT: Webhooks enable real-time event-driven integrations, but they are notoriously difficult to implement correctly. Unlike request-response APIs, webhooks reverse the relationship: your server calls their server, and everything that can go wrong will. Developers routinely make mistakes with signature verification, idempotency, and error handling that lead to security vulnerabilities and lost events.

TASK:
1. Webhook Overview & Event Catalog — Explain what webhooks are, how they differ from polling, and when to use each approach. For each webhook event type, document the event name, trigger conditions, complete payload JSON schema, field descriptions, and a realistic example payload. Group events by resource type.
2. Endpoint Setup & Configuration — Walk through registering a webhook endpoint including URL requirements (HTTPS, public accessibility), supported content types, and expected response codes. Show complete endpoint implementations in Node.js, Python, and Go. Include health check endpoint patterns for monitoring.
3. Signature Verification Implementation — Provide step-by-step instructions for verifying webhook signatures including where to find the signing secret, the exact HMAC-SHA256 algorithm, timing-safe comparison, and replay attack prevention using timestamps. Include complete code examples in three languages. Emphasize this is mandatory with clear vulnerability explanations.
4. Retry Policy & Failure Handling — Document the retry schedule (immediate, 5 min, 30 min, 2 hours, 24 hours), which HTTP codes trigger retries versus permanent failures, maximum attempts, and the dead letter queue. Show how to view failed deliveries and manually replay events. Include alerting setup for persistent failures.
5. Idempotency & Event Ordering — Explain why webhook consumers must be idempotent with concrete examples of duplicate delivery scenarios. Show database-backed deduplication patterns using the event ID. Address out-of-order delivery handling using event timestamps and sequence numbers. Include a state machine pattern for entity lifecycle events.
6. Testing, Debugging & Best Practices — Document testing tools: CLI simulators, dashboard replay, ngrok for local development, and mock webhook servers. Show how to inspect delivery logs and debug failed deliveries. Cover best practices: acknowledge immediately then process async, queue-based processing, monitoring for delivery gaps, and alerting on signature failures.