Guide — message correlation & tenant routing for platform mode

Released: August 29, 2026

Message correlation & tenant routing guide Added

Multi-tenant platforms (a SaaS onboarding many end-customers, each with their own WhatsApp number) repeatedly ask the same two questions:

1. A message.status webhook lands on my single URL — which end-customer does it belong to?
2. I sent a message and got a msg_… id, but the status webhooks speak wamid.… — how do I link them?

The facts were already documented across the platform, event, and payload references; this new page pulls them into one deterministic, end-to-end recipe so you don’t have to stitch them together yourself. It covers:

• Using phone_number_id (learned from customer.onboarded) as the join key from a tenant to every message event.
• The two consumption models — one URL routed by phone_number_id, or one subscription per customer scoped by phone_number_ids.
• Correlating msg_… ↔ wamid.… via message.sent, including that webhook order is not guaranteed (buffer status by wamid).
• Failed sends: wamid for post-Meta failures, msg_… for pre-Meta failures, correlated directly.
• What retention removes, and why you should persist the mapping yourself.

No API or webhook behavior changed — this is documentation only.

Read the guide →