使用ngrok本地测试时WhatsApp Webhook回调数据接收相关问题

一、不同回调场景对应的HTTP请求方法 #

WhatsApp Business Platform对webhook的请求按流程分为两类，你之前调试通过的GET请求仅覆盖验证环节：

• GET请求：用于webhook所有权校验，配置webhook时平台会附带hub.mode、hub.verify_token、hub.challenge参数发起请求，只要校验token匹配后原样返回hub.challenge值即可完成验证，这部分逻辑你已经调试正常。
• POST请求：所有真实业务回调（用户发送的消息、消息投递状态更新、用户互动事件等）全部通过POST方法推送，这是目前你缺失处理逻辑的核心环节。

注意：webhook路由必须同时开放GET和POST的方法权限，仅配置GET处理逻辑会导致POST请求被服务端框架直接拦截，出现平台配置正常但收不到回调数据的问题。

二、回调数据的正确解析方式 #

所有POST类型的回调请求均为application/json格式的结构化数据，不存在表单编码的变体，解析时按固定层级遍历即可，完整处理流程如下：

1. 前置安全校验
   平台会在请求头携带X-Hub-Signature-256字段，值为通过你的应用 Secret 对原始请求体计算的HMAC-SHA256签名。你需要使用未被框架篡改的原始请求体字符串计算签名，和请求头中的值比对一致后再进入解析环节，避免接收伪造的恶意请求。
2. 结构化字段取值
   回调JSON的结构有固定的通用规范，无需依赖自定义表单解析逻辑：
   • 顶层固定包含object字段（值固定为whatsapp_business_account）
   • 顶层entry为数组结构，聚合对应WhatsApp商业账号的所有事件
   • 每个entry元素下的changes为数组结构，存放单条独立事件
   • 每个change元素下的value字段是实际业务数据的承载对象，根据事件类型不同，子字段有明显区分：
     • 存在messages字段：代表用户发来的新消息，遍历该数组即可获取消息ID、发送者号码、消息类型（文本/图片/语音等）、具体消息内容、发送时间戳
     • 存在statuses字段：代表你主动发送的消息的投递状态（已发送、已送达、已读、发送失败等）
     • 存在contacts字段：代表发消息用户的公开profile信息（昵称等）

常见调试排查思路：

• 先用curl命令模拟POST请求携带测试JSON体打到你的ngrok公网地址，验证控制器能否正常接收到请求体，排除路由方法拦截、权限校验的问题
• 若本地模拟请求可正常接收，可到Meta开发者后台查看webhook的事件交付日志，定位是否存在请求被服务端返回4xx/5xx错误的情况

内容的提问来源于stack exchange，提问作者Roberto Vieira