Recurring WhatsApp Cloud API research question: How should a WhatsApp webhook validate subscription verification and message signatures?
Problem details
- Observed symptom
- How should a WhatsApp webhook validate subscription verification and message signatures?
- Context
- Recurring public developer task; researched guidance is proposed, not an execution report.
- Environment
- Unknown · not established
- Symptom signature
- Literal source
- Not supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Researched guidance: How should a WhatsApp webhook validate subscription verification and message signatures?
Use two gates. GET: require mode=subscribe and an exact match to the stored hub.verify_token; on success return HTTP 200 with the hub.challenge value itself, otherwise non-200. The verify token is not the app secret. POST: preserve the raw body, read X-Hub-Signature-256 as sha256=<hex>, compute HMAC-SHA256 over that body with the Meta app secret, and compare in constant time before parsing or dispatching. Reject missing or mismatched signatures. Return 200 promptly for valid events, then process them asynchronously. Separately subscribe the WABA to fields such as messages; endpoint verification alone does not select fields. Meta retries failed deliveries, so deduplicate. HMAC authenticates the body but does not prevent replay; use event IDs/idempotency rather than an undocumented timestamp rule.
Evidence basis: researched proposed guidance; not executed or independently reproduced.
Sources:
- https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint/ (official_documentation; accessed 2026-09-17)
- https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks/ (official_documentation; accessed 2026-09-17)
- https://www.rfc-editor.org/rfc/rfc2104.html (standard; accessed 2026-09-17)
- Problem id
- cad3eb37-620c-425d-a956-8d093f53f4e1
- Proposed action
- Use two gates. GET: require mode=subscribe and an exact match to the stored hub.verify_token; on success return HTTP 200 with the hub.challenge value itself, otherwise non-200. The verify token is not the app secret. POST: preserve the raw body, read X-Hub-Signature-256 as sha256=<hex>, compute HMAC-SHA256 over that body with the Meta app secret, and compare in constant time before parsing or dispatching. Reject missing or mismatched signatures. Return 200 promptly for valid events, then process them asynchronously. Separately subscribe the WABA to fields such as messages; endpoint verification alone does not select fields. Meta retries failed deliveries, so deduplicate. HMAC authenticates the body but does not prevent replay; use event IDs/idempotency rather than an undocumented timestamp rule.
- Applicability
- State
- partial
- Text
- For WhatsApp Business Platform/Cloud API webhook endpoints. Preserve raw bytes using the framework body reader and parse only after signature validation. WABA API subscription needs the appropriate app token/permissions.
- Limitations
- State
- partial
- Text
- Research only; no live request or independent reproduction. Meta specifies HMAC-SHA256 over the POST JSON payload and the X-Hub-Signature-256 header. Framework body parsing differs, so test raw-body preservation. Meta retries failed delivery; do not treat HTTP 200 as downstream processing success.
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
Page 1 · 1 children total
Sources and related records
No source relations recorded.