WhatsApp Business API消息Webhook无法触发，其余Webhook正常

问题概述 #

WhatsApp Webhook的messages事件完全无法触发，但flows、security、account_alerts等其他类型的Webhook测试均能正常接收回调。

环境信息 #

• 使用WhatsApp Business API
• 在Facebook Webhook测试页进行测试
• Facebook应用处于Live模式

问题详情 #

• 除messages事件外，所有Webhook测试均成功接收
• 以下场景均无Webhook触发：
  1. 从Facebook Webhook测试页发送测试消息
  2. 直接向已注册的WhatsApp号码发送真实消息

当前使用的Webhook代码示例 #

// 简化版Webhook处理器示例
app.post('/webhook', (req, res) => {
  const body = req.body;
  console.log('Webhook received:', body);
  
  if (body.entry && body.entry[0].changes) {
    // Webhook处理逻辑
  }
  
  res.sendStatus(200);
});

排查与修复步骤 #

1. 确认Webhook事件订阅权限 #

进入Facebook开发者后台对应应用的Webhook配置页，检查messages事件是否已被勾选订阅，且权限状态为激活状态。注意：即使应用在Live模式下，未明确订阅的事件不会被推送。

2. 验证WhatsApp号码关联状态 #

确认测试用的WhatsApp号码已正确关联到当前应用的WhatsApp Business账户，且号码已完成身份验证、处于“已启用”状态。新添加的号码需确保激活流程全部完成。

3. 扩展日志排查请求情况 #

修改代码增加详细日志，确认是否有messages类型的请求被接收：

app.post('/webhook', (req, res) => {
  // 打印请求头和原始请求体，需确保框架支持获取原始体（如Express需配置body-parser）
  console.log('请求头:', req.headers);
  console.log('原始请求体:', req.rawBody);
  const body = req.body;
  console.log('解析后的请求体:', body);
  
  if (body.entry && body.entry[0].changes) {
    // 遍历所有变更，打印事件类型
    body.entry[0].changes.forEach(change => {
      console.log('事件类型:', change.field);
      console.log('事件内容:', change.value);
    });
  }
  
  // 快速返回响应，避免超时
  res.sendStatus(200);
});

• 如果日志里完全没有messages相关请求，说明Facebook未推送，回到权限和号码配置检查；
• 如果有请求但未触发处理逻辑，调整代码中的判断条件。

4. 确保Webhook响应及时 #

Facebook要求Webhook在15秒内返回200状态码，若处理逻辑耗时过长，会导致Facebook停止推送。优先返回响应，复杂逻辑用异步任务处理。

5. 检查服务器IP白名单 #

如果服务器设置了IP白名单，需将Facebook官方的WhatsApp Webhook回调IP段加入白名单。

6. 重新订阅Webhook事件 #

在Webhook配置页先取消订阅messages事件，保存后重新勾选并验证。部分场景下订阅状态异常，重新订阅可修复。

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