钉钉机器人 webhook 返回报错 310000 多数场景下表示请求服务器的 IP 地址未添加到机器人安全设置的白名单中。解决方向是查询出口 IP 并在钉钉后台配置放行，注意动态 IP 环境可能导致配置失效。
先说结论：报错 310000 核心原因是 IP 白名单校验未通过，需将发送请求的服务器公网 IP 加入钉钉机器人安全设置。
- 先确认：查询发送请求服务器的出口公网 IP 地址
- 先处理：在钉钉机器人管理后台将该 IP 加入白名单
- 再验证：重新发送 webhook 请求确认报错消失
命令速用版
在发送请求的服务器上执行以下命令，查看出口 IP 地址：
curl ifconfig.me或使用钉钉提供的测试发送功能前，确保本地网络 IP 已录入。
为什么会这样
钉钉机器人 webhook 接口启用了 IP 白名单安全机制，防止恶意调用。
当请求头中的来源 IP 与管理后台配置的不一致时，接口会拦截请求并返回 310000 错误码。这是钉钉开放平台设定的默认安全策略，未配置白名单或配置错误均会触发。
分步处理
按以下顺序操作，确保配置准确：
- 获取出口 IP：在部署代码的服务器或网关设备上，使用 curl 命令查询公网 IP。若经过 NAT 网关，需查询网关出口 IP 而非内网 IP。
- 进入配置页：登录钉钉管理后台，进入机器人管理页面，找到对应的自定义机器人。
- 添加白名单：在安全设置区域选择“IP 地址白名单”，将上一步获取的 IP 填入并保存。若有多台服务器，需全部添加。
- 检查关键词：若同时开启了“自定义关键词”，确保消息内容中包含该关键词，否则可能报其他错误。
怎么验证是否生效
配置完成后，再次触发业务代码发送 webhook 请求。
观察返回 JSON 数据，若 errcode 变为 0 且 errmsg 为 ok，则表示生效。也可在钉钉群内查看是否收到消息通知。
常见坑
- 动态 IP 环境：若服务器出口 IP 不固定，每次变化都会导致报错，建议使用固定 IP 代理或切换签名验证方式。
- 多出口网络：服务器有多个网卡或路由时，请求可能从不同 IP 发出，需确保所有可能出口 IP 均加入白名单。
- 本地测试：本地开发环境直接调用会因本地 IP 未白名单而失败，需临时添加本地 IP 或通过服务器中转。
常见问题
服务器 IP 变了怎么办？
需重新登录钉钉后台更新白名单 IP，或改用加签验证方式避免 IP 限制。
加了白名单还是报 310000？
检查是否经过多层代理，实际请求 IP 可能与查询 IP 不一致，建议在请求日志中打印实际来源 IP 核对。
必须同时配置关键词吗？
不是，IP 白名单和自定义关键词是两种独立的安全设置，任选其一或同时开启均可，但需满足对应校验规则。
参考来源
- 钉钉开放平台，自定义机器人安全设置，https://open.dingtalk.com