跳转到主要内容

安全

Webhook 的可靠性既取决于 Unico 的投递保证，也取决于您端点的行为。本页介绍您的端点必须遵守的三个不变量：幂等性、并发限制和错误率。

幂等性​

Unico 的 Webhook 实现保证至少一次投递——同一 processId 的相同状态可能被通知多次。您的端点必须具备幂等性。

推荐模式：

  1. 每次收到 Webhook 调用时，首先检查 processId 是否已被处理。
  2. 若已处理，立即返回 2xx（任务已完成）。
  3. 若未处理，执行业务逻辑并持久化该 processId 已处理的记录。
// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}
为何重要

非幂等端点会在每次投递时执行业务逻辑（例如扣款、发送邮件），一旦发生重试就会重复触发——而重试在 Webhook 投递中是正常现象，并非异常。

并发限制​

为保护您的端点在高流量期间免受峰值冲击，请在注册 Webhook 时配置最大同时在途投递数量（上限：500）。

当达到并发限制时，Unico 会将额外的投递排队，并在容量释放后继续处理。结合重试机制，持续的流量峰值可能会延长新 Webhook 的实际投递时间。

错误率​

错误率（200–299 范围之外的响应）应始终保持较低水平。如果您的端点开始大规模返回错误，Unico 将自动降低该端点的 Webhook 吞吐量。结合重试机制，这可能会显著增加新 Webhook 的执行时间。

运维建议：

  • 在您侧监控非 2xx 响应。当持续错误率超过正常基线时触发告警。
  • 将 Webhook 处理器视为关键路径——它应该是您技术栈中最可靠的服务之一。
  • 计划维护时，建议在负载均衡器层面停止接入，而非返回 503。持续的非 2xx 响应（包括 503）会触发上述自动吞吐量限流；当端点恢复后，降低的吞吐量会延迟投递停机期间积压的事件。对于未处理的事件，请勿返回 200。

状态语义​

将 state 和 lastEvent 的值集合视为可演进的配置：

  • 仅对您明确处理的状态/事件作出响应。
  • 记录未知值——不要因为未知值而报错。
  • 新状态可能在不升级主版本的情况下被添加。
最后更新 于