Understand Meta webhook verification

Platform-managed callback

GET verification

• Meta sends hub.mode=subscribe, hub.verify_token, and hub.challenge.
• The platform requires a configured verification token and exact match.
• Success returns hub.challenge as text/plain. Every invalid or unavailable configuration returns 403 with Forbidden.
• Never place a real verification token in documentation, logs, screenshots, or support examples.

POST signature verification

• The exact raw request body is verified against x-hub-signature-256 using the configured app secret.
• Missing configuration or invalid signature fails closed with 403 Invalid signature.
• Valid requests process inbound messages, status, history, state sync, and echo events and return received true.
• Inbound message state is persisted before active On Message Flows run; status work is queued so Meta can safely retry failed callback processing.

Safe conceptual example

GET /api/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=<redacted>&hub.challenge=<challenge>

POST /api/whatsapp/webhook
x-hub-signature-256: sha256=<redacted>
Body: signed Meta webhook JSON

Examples must remain redacted. Do not publish app secrets, verification tokens, real signatures, phone-number IDs, WABA IDs, customer payloads, or operational diagnostics.