The best practice is to acknowledge the webhook immediately (return 200), then queue the event for asynchronous processing. This prevents timeouts and retries while still handling the event.

If the receiver doesn't return a 2xx status (or times out), the sender retries. The receiver might be processing successfully but returning an error status or taking too long to respond.

503 is a temporary error (server overloaded). Queue for retry with exponential backoff (e.g., 1min, 5min, 30min). This gives the receiver time to recover without overwhelming it.

HMAC signatures are computed on the exact bytes received. JSON.parse() can change whitespace, key ordering, or number formatting. Always verify the raw body string, then parse.

With a 5-minute (300 second) tolerance, this event is too old (501 seconds). It could be a replay attack or indicate clock issues. Reject it and investigate if this happens frequently.

Expose business-meaningful events that customers would want to react to. The full order lifecycle (created, updated, shipped, delivered, cancelled) covers the main use cases.

Events can arrive out of order. Use the event timestamps (not arrival time) to determine the correct state. Or better, fetch the current state from the API after receiving any event.

Signature verification is the primary defense. Without the shared secret, attackers cannot create valid signatures. Rate limiting and IP allowlisting are secondary defenses.

Move permanently failed webhooks to a dead letter queue (DLQ). This preserves the data for investigation and manual retry once the issue is resolved. Never lose events silently.

Webhook providers typically retry for a limited time (e.g., Stripe retries for 72 hours). After that, the event won't be redelivered. TTL prevents your idempotency store from growing forever.

Including the timestamp in the signed payload (like Stripe's t=timestamp,v1=signature format) prevents replay attacks. An attacker can't reuse an old signature because changing the timestamp invalidates it.

Never block webhook handlers with slow operations. Return 200 immediately, queue the event, and process it in a background worker. This prevents timeouts and retries.

If incoming HTTP isn't possible, offer alternatives: API polling (they call you), WebSockets (outbound connection from their side), or a pull-based queue system.

Disable endpoints that fail consistently over an extended period (e.g., 3+ days of failures). This saves resources and prevents queueing events that will never be delivered. Notify the customer so they can fix and re-enable.

Let customers specify which event types they want when configuring their endpoint. This reduces unnecessary traffic and processing on both sides. Send only the events they've subscribed to.