Google Actions Webhook与Web集成问题：测试返回[empty response]

阿华AIGC实验室

2026-5-25

我之前调试Google Actions Webhook时也踩过这个坑，显示[empty response]大多是因为Webhook的响应不符合要求或者请求链路出了问题，给你梳理几个最常见的排查方向：

响应格式不符合Google Actions规范
Google Actions对Webhook的响应结构有严格要求，必须包含fulfillmentText或fulfillmentMessages字段，且JSON结构不能出错。比如一个最小的有效响应应该是这样的：
```
{
  "fulfillmentText": "你好，这是Webhook返回的响应"
}
```
如果你返回的JSON缺少这些必填字段、嵌套层级错误，或者字段名拼写错误（比如把fulfillmentText写成fulfillmenttext），就会触发空响应提示。建议先用Postman直接调用你的Webhook API，确认返回的JSON结构完全符合要求。
Webhook请求超时或内部报错
Google Actions要求Webhook在5秒内返回响应，如果你的API处理逻辑太复杂、数据库查询太慢，或者服务器抛出了500/404等错误状态码，都会导致平台无法获取有效响应。可以检查你的服务器日志，看看有没有报错信息；同时测试API的响应时间，确保在超时阈值内。另外还要确认你的Webhook地址是公开可访问的，没有被防火墙、CDN或者CORS策略拦截。
Intent的Webhook触发配置有误
有时候问题出在Intent的设置上：你需要确认目标Intent的「Fulfillment」选项卡中，已经勾选了「Enable webhook call for this intent」，并且关联的Webhook URL是正确的（比如没有拼写错误、端口号正确）。如果没开这个开关，Intent只会返回你在控制台设置的静态响应，而不会调用Webhook。
请求体解析错误
Google Actions发送给Webhook的请求是特定格式的JSON，包含意图参数、用户会话等信息。如果你的代码没有正确解析这个请求体（比如用了错误的解析方式，或者取错了字段），可能导致逻辑分支出错，最终没有生成有效响应。建议把收到的请求体打印到日志里，对比Google Actions的官方请求结构，检查你的解析逻辑是否正确。
SSL证书不被信任
Google要求Webhook必须使用HTTPS协议，如果你的服务器使用的是自签名证书、过期证书，或者证书链不完整，Google的服务器会拒绝建立连接，自然无法获取响应。测试环境可以用ngrok这类工具转发本地服务，它提供的证书是被信任的；生产环境则需要使用主流CA颁发的有效SSL证书。