Webhook 维护：暂停 worker、停用端点，还是删除？

如果维护的只是下游业务，优先让 webhook 接收器继续验签和持久化事件，暂停消费事件的 worker。停用 UnifyPort 端点会把状态设为 inactive，但保留端点配置；删除则移除端点。两者都不是文档承诺的“暂停后补发”服务。先明确要停止哪一层，再选择控制方式。

要点

• CRM、AI 流程或 worker 维护时，优先在持久化接收之后暂停业务处理。
• 只有确实需要停用端点时才执行停用，并明确接受和排查潜在投递缺口。
• 删除用于退役端点，不应作为临时部署开关。
• 返回 503 不能换取维护时间：UnifyPort 会立即重试，没有退避等待。

三种控制方式的区别

第一种是建议的应用架构，后两种是 UnifyPort 文档明确提供的控制面操作。

控制方式	改变什么	仍由你负责什么
暂停应用 worker	消费者停止处理，健康的接收器继续持久化事件	队列容量、保留策略、恢复检查点和副作用幂等
停用端点	状态变为 inactive，端点不被删除	记录中断、验证重新启用、调查遗漏区间
删除端点	端点资源被移除	再次需要服务时创建并验证新端点

停用端点文档对应 POST /v1/webhook-endpoints/{endpoint_id}/deactivate。删除端点文档对应 DELETE /v1/webhook-endpoints/{endpoint_id}，成功返回 204 No Content。

这些操作控制的是 webhook 端点，不应被当作账号退出登录、运行连接停止或已接收任务的取消操作。已经领取任务的 worker 仍可能执行完毕；要停止这类副作用，需要应用自己的处理控制。

为什么优先暂停 worker

假设团队要部署 CRM 集成，但仍希望 LINE 和 WhatsApp 消息进入收件箱。这是架构示例，不是客户案例或已实现的结果。

将接收链路与 CRM 分开：

1. 用原始请求字节验证签名和时间戳。
2. 校验事件并提交到持久化存储。
3. 返回成功确认。
4. 由独立 worker 执行 CRM 写入、AI 调用或通知。

暂停消费者前，确认接收存储在维护期间持续可用。为队列增长、数据保留设置运行边界，并指定存储故障的处理负责人。进程中的内存数组不能充当可承受重启的维护缓冲区。

部署结束后，从已提交的处理状态继续消费。入口返回过 2xx，不代表积压任务已经完成。Webhook-first 接入清单说明最初的持久化边界；维护流程还需要单独控制消费者何时执行动作。

如果要维护的正是接收存储，这个方案并不够。接收器和存储都必须下线时，应准备经过验证的替代接收链路，或明确记录并接受中断，不能未经验证就承诺持续收集。

为什么错误响应不是暂停机制

投递契约说明：连接错误以及 408、429、5xx 会立即重试。retry_policy.max_attempts 表示首次请求之后的重试次数，默认三次；没有退避，且不遵循 Retry-After。其他 4xx 会停止自动投递并将事件标记为死信。

因此，部署期间持续返回 503 可能耗尽尝试次数，而不是把投递推迟到恢复之后。返回 200 却丢弃载荷更不可取：这等于确认了尚未持久化的数据。死信状态也不代表存在可供调用的重放操作。

维护期间继续启用签名验证。空的 signing_secret 会关闭签名，不会暂停投递。需要更换凭据时，采用独立的签名密钥轮换流程，不要把认证变更和端点退役混在一起。

确实要停用时，设置明确的恢复门槛

变更前，使用获取端点配置记录端点 ID、URL、状态、订阅事件、签名状态和重试策略。实际签名密钥应留在受保护配置中，不写入变更日志。同时列清依赖这个端点的下游流程。

停用选定端点后，再读取配置确认状态。把操作时间及结果与应用队列状态分开记录。公开文档没有说明在途请求全部排空的保证，也没有承诺补发停用期间的事件；成功响应不能证明这两点。

恢复时使用更新端点，将 status 设为 active 并提交经审核的配置。保留目标 URL、订阅、重试策略及非空签名密钥，不要把示例中的停用或无签名配置直接复制到生产环境。

重新读取配置，确认 signing_enabled: true，然后向已连接的消息账号发送受控测试消息。跟踪对应的 message.received，验证验签、持久化和目标 worker 处理。这只能证明新事件链路正常，不能证明停用期间的数据已经恢复。

如果控制面请求超时，先检查当前端点，再决定下一步变更。保留不含秘密的请求诊断信息。接收器安静不代表停用已完成；重新启用成功也不代表业务处理已恢复。

删除及恢复的边界

只有确认不再需要端点并记录依赖关系后才删除。删除成功没有 JSON 响应体，不要尝试解析。以后创建替代端点属于重新配置，不是恢复旧端点遗漏的投递。

UnifyPort 的非官方接口提供规范化的消息账号事件，但没有通用 REST 消息历史读取 API，也不保证遗漏载荷重放。有限的 WhatsApp 历史机制不是跨渠道维护恢复保证。

恢复已存储任务时，采用文档定义的去重边界：普通事件重试复用 X-Device-Event-Id；conversation.history 批次需要按消息合并，不能只按该头部做全局去重。发送等业务副作用仍需要独立幂等控制。

常见问题

停用会保留端点吗？

会。状态变为 inactive，端点不会删除。但这不构成积压保留或重放保证。

可以只暂停 AI 流程吗？

可以在应用中暂停该消费者，让接收器继续验签和持久化。这不是额外的 UnifyPort API 设置。

部署时应该删除再创建吗？

通常不应该。下游维护优先暂停消费者；必须中断端点时则规划中断。删除是退役决策。

下一步与参考资料

先阅读投递契约，写清维护实际停止哪一层，再修改生产配置。

产品资料核对日期：2026-10-06。

• 停用 webhook 端点
• 更新 webhook 端点
• 删除 webhook 端点
• 投递、确认和重试