UnifyPort 账号 Webhook:为什么工作空间收不到部分事件
如果 UnifyPort 工作空间 Webhook 能收到其他消息账号的事件,却收不到某一个账号的事件,应先检查该账号的独立 Webhook 配置。账号配置会覆盖工作空间配置。 独立端点处于 inactive,或没有订阅某个事件,都不会让该事件自动转到工作空间。删除最后一个独立端点,才会为后续首次投递恢复继承;这不代表补发旧事件。
核心要点
- 工作空间端点与账号端点是不同配置作用域,不是主备关系。
- 必须分别查询:不带账号参数的端点列表只包含工作空间端点。
- 账号列表为空表示没有独立配置,不等于没有有效接收路径。
- 停用保留覆盖关系;恢复继承需要移除最后一个独立端点。
- 路由选择、事件订阅、签名验证与账号连接状态应分开排查。
哪一层配置决定事件去向?
创建 Webhook 端点文档定义了可选请求体字段 account_id:传入它,将端点绑定到该消息账号;省略它,创建工作空间端点。响应中的独立端点带有 account_id,工作空间端点则省略该字段。
修改订阅前,先按下表判断路由:
| 账号独立配置 | 工作空间继承 | 应检查什么 |
|---|---|---|
| 没有独立端点 | 生效 | 工作空间端点状态与订阅 |
| 有 active 独立端点,且订阅匹配 | 被覆盖 | 账号接收服务与签名配置 |
| 有独立端点,但全部 inactive | 不自动回退 | 是否仍需要独立配置 |
| active 独立端点没有订阅目标事件 | 不自动回退 | 账号端点的事件订阅 |
| 最后一个独立端点已删除 | 后续首次投递恢复继承 | 工作空间接收能力及新事件验证 |
假设工作空间收集器订阅了 message.received,某个账号的独立端点却只订阅 account.status.updated。这是配置示例,不是实际事故。工作空间订阅不会补足账号筛选器遗漏的消息事件。应修正账号配置,或明确决定恢复继承。
事件筛选指南解决“选哪些事件”的问题;这里更先要回答:这个账号的投递由哪个作用域负责?
用两次只读请求查看两个作用域
两次请求使用同一个服务端 X-Api-Key,由密钥确定工作空间。以下仅演示请求路径,acc_example 应换成账号查询返回的真实公开 ID:
GET /v1/webhook-endpoints
GET /v1/webhook-endpoints?account_id=acc_example
列出 Webhook 端点文档说明:第一次只返回工作空间端点;第二次只返回该账号的独立配置,不包含继承来的工作空间端点。因此,第二次成功响应中的 data: [] 表示“没有独立账号端点”,不能解释成“没有 Webhook 接收路径”。
记录端点 ID、账号绑定、URL、status、subscribed_events、signing_enabled 与重试策略。不要只看 active 项,inactive 项也影响继承。诊断记录中不要保存密钥或消息正文。
参数名必须准确写成 account_id。空值、纯空白、重复参数和大小写变体都不等于省略。明确指定的账号不存在或不属于当前工作空间,会返回 404 account_not_found;应修正标识和工作空间,不能当作空列表处理。
如果两层配置都正确,再检查下一层:分别确认授权和 runtime 状态,追踪一条受支持的新事件是否通过接收端认证并持久化。不要因为错误 URL 没收到请求,就重启健康的消息账号。
修复独立配置,还是恢复继承?
保留账号专用接收服务
使用更新 Webhook 端点修正现有端点的目标 URL、启用状态或订阅,同时保留经过确认的签名与重试配置。空 signing_secret 会关闭签名,不要把未签名示例直接复制到生产环境。
当同一账号已有 active 独立端点时,再创建一个 active 独立端点可能返回 409 account_webhook_already_exists,数字码为 40008。将另一个端点从 inactive 改为 active 时也有此限制。已处于 active 的端点保持 active 更新则允许,包括历史遗留的多个 active 配置;系统不会自动清理这些旧配置。此启用名额规则不限制工作空间端点。
账号绑定本身不可修改。更新时传入 account_id 只是验证原归属,省略则保留归属。省略或传 null 都不能将账号端点转换为工作空间端点,也不能把既有工作空间端点重新分配给账号。
让账号重新使用工作空间接收服务
先确认工作空间接收端已启用,订阅了所需事件,且验签和持久化存储准备就绪。与账号专用工作流的负责人确认影响。
再通过删除 Webhook 端点明确移除独立配置。检查每个独立条目:留下 inactive 端点仍会保留账号配置。重新查询账号作用域,确认已没有独立端点。删除成功返回 204,没有响应正文。
这是路由调整,不是一般维护建议。如果只是临时暂停 CRM 或 AI 处理,Webhook 维护方式对比说明了为何暂停下游 worker 往往比更改端点配置更合适。
验证新路径,不承诺补齐历史
配置调整后发送一条受控测试消息,在预期接收端确认账号和事件,按照投递契约验签,持久化成功后再确认接收。下游处理是否成功应另行验证。
这些是建议的验收步骤,不是已经在你的工作空间执行的测试。配置请求超时后,先读取当前状态,再决定是否重复修改。文档的继承规则针对后续首次投递,不保证每个在途请求都会如何变化。
UnifyPort 非官方接口提供统一事件接收路径,不保证重放遗漏的载荷。新测试成功只证明新路径可用,不证明此前缺失区间已经恢复。
常见问题
停用账号端点后,工作空间会接手吗?
不会。inactive 独立配置仍会覆盖工作空间。删除最后一个独立端点,才会为后续首次投递恢复继承。
把工作空间订阅改成通配符能解决吗?
不能解决账号覆盖问题。应检查实际生效的账号配置,或有计划地移除它以恢复继承。
账号端点列表为空是什么意思?
成功的空结果表示该账号没有独立端点。应继续读取工作空间列表,检查继承配置。错误响应不能视为空结果。
下一步与参考资料
先打开列出 Webhook 端点,比较两个作用域,再决定是否修改。
官方产品文档核对日期:2026-11-15。
让消息接入变成一条稳定的产品管线。
先用统一 API 跑通发送,再用标准事件把所有入站消息接回业务系统。