WhatsApp Cloud API回调URL无法接收Hub参数问题排查

以下是你可能遗漏的配置或常见问题，按优先级排查：

• 确认Webhook验证的触发逻辑
  Meta的Webhook验证请求仅在你在开发者后台点击「Verify and Save」按钮时才会发送，发送测试消息或主动调用不会触发带hub.mode等参数的GET请求。先回到Meta开发者后台的Webhook配置页，确认你已经填写完回调URL和Verify Token，并点击了验证按钮，这是触发验证请求的唯一方式。

• 检查回调URL的一致性
  确保Meta后台填写的回调URL和你实际部署服务的URL完全一致：

  • 必须使用HTTPS（本地测试可通过ngrok等隧道工具生成HTTPS地址，正式环境强制要求）；
  • 路径、端口号（非443端口需明确标注）不能有拼写错误，比如后台填https://yourdomain.com/wa-webhook，但你的服务路由是/webhook，就会导致请求无法正确到达；
  • 注意URL的大小写（虽然URL本身不区分大小写，但部分框架的路由是严格匹配的）。

• 排查反向代理/网关的参数转发
  如果你的服务前有Nginx、Apache或云API网关：

  • 以Nginx为例，proxy_pass配置必须包含$request_uri来完整转发请求路径和查询参数，正确配置示例：

    location /webhook {
        proxy_pass http://localhost:3000$request_uri;
    }
    

  • 检查网关是否有过滤查询参数的规则，确保hub.mode、hub.challenge、hub.verify_token这三个参数能被正常传递到你的服务。

• 检查防火墙与安全组规则

  • 确认服务器防火墙、云安全组允许Meta的Webhook IP段访问你的服务端口；
  • 若启用了WAF（Web应用防火墙），暂时关闭或添加规则允许包含hub_前缀参数的GET请求，避免被误拦截。

• 本地测试的隧道工具配置
  如果用ngrok等本地隧道工具：

  • 确认隧道处于运行状态，且后台配置的URL和隧道生成的最新地址一致（隧道重启后URL会变化）；
  • 检查隧道工具是否支持转发查询参数，部分工具需手动开启参数转发功能。

• 代码路由与参数解析检查

  • 验证请求是GET方法，参数在查询字符串中，不要错误地从POST body中读取；
  • 检查框架中间件是否有修改或清空查询参数的逻辑，比如某些自定义中间件可能会过滤非预期参数。

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