Reliable WhatsApp Webhooks: From Delivery to Durable Processing

Channel providers retry when acknowledgements are slow or connections fail, so the same event can arrive more than once. Events may also be delayed or observed out of order. Treat each request as an attempt to deliver an event, validate it, and place it into your processing system rather than as a command that must finish synchronously.

Keep the ingress path small. Authenticate the request, validate its shape and size, resolve the trusted instance mapping, derive a stable event identity, persist a safe envelope, and respond. AI calls, media downloads, database enrichment, and outbound replies belong in workers where timeout and retry behavior can be controlled.

Returning success before recording the event can lose messages when the process crashes between acknowledgement and enqueue. Returning success after full AI processing makes the provider retry ordinary slow work. The useful boundary is durable acceptance: the event is stored transactionally or acknowledged by a durable queue before the webhook returns.

Use a uniqueness constraint on provider, instance, and provider event identifier where available. If an identifier is missing, derive a conservative fingerprint from stable fields without treating mutable content as identity. Record duplicate receipt for diagnostics, but do not repeat customer-visible side effects.

The provider retries webhook delivery; your worker retries processing; the outbound client retries sending. These are different state machines and should have different limits, delays, and error classifications. A malformed event is terminal, a temporary database outage is retryable, and an invalid recipient may require operator action instead of endless retries.

Use exponential backoff with jitter for transient dependencies and cap retry duration according to customer value. Move exhausted work to a visible failure state with enough safe context to replay deliberately. Silent dead-letter queues merely relocate message loss from code into operations.

Strict global ordering reduces throughput and is rarely necessary. What usually matters is ordering within a conversation or contact for actions that depend on previous state. Partition those events by a stable conversation key, while allowing unrelated conversations and tenants to process in parallel.

Rapid messages may benefit from a short aggregation window so the AI responds to the customer's complete thought rather than each fragment. Make this behavior explicit and bounded. Status events, media updates, and user messages can follow different paths as long as their resulting state changes remain coherent and idempotent.

Monitor accepted event rate, duplicate rate, queue age, processing latency, retry reasons, terminal failures, and outbound delivery state. Correlation identifiers should connect ingress, worker runs, AI calls, tool actions, and sends without exposing message content. Tenant-level views help distinguish a platform incident from one broken provider connection.

Run failure drills for database unavailability, worker restarts, provider timeouts, malformed payloads, duplicate bursts, and delayed media. Verify that accepted events survive, retries do not create duplicate replies, and operators can find and replay failures. Reliability is proven by recovery behavior, not by a quiet dashboard during normal traffic.