Skip to main content

Webhook Ordering Protection

Meta WhatsApp webhooks can arrive out of order, duplicated, or significantly delayed. The system relies on Monotonic State Transition rules to prevent invalid rollbacks (e.g., preventing a message from going from DELIVERED back to SENT).

Monotonic State Precedence​

States have assigned weights:

  1. ACCEPTED (Weight: 10)
  2. SENT (Weight: 20)
  3. DELIVERED (Weight: 30)
  4. READ (Weight: 40)
  5. FAILED (Weight: 50)

State Transition Validation​

When a webhook arrives, the system queries the current state weight.

  • If NewWeight > CurrentWeight: Update state.
  • If NewWeight <= CurrentWeight: Ignore payload, return 200 OK (out-of-order or duplicate).

Reconciliation Architecture​

Replay Cache Lifecycle​

  • A Redis SET NX lock webhook:nonce:{wamid} prevents instantaneous duplicates.
  • The TTL for this replay cache is strictly set to 48 hours, covering Meta's maximum retry window.