---
title: 安全
description: 如何验证和保护 IDCloud Webhook 负载 — 签名验证与最佳实践。
canonical: https://developer.unico.io/zh-CN/dual-api/developers/webhooks-and-events/security
locale: zh-CN
generated_by: markdown-export
---

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

### 幂等性

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

推荐模式：

1. 每次收到 Webhook 调用时，首先检查 `processId` 是否已被处理。
2. 若已处理，立即返回 `2xx`（任务已完成）。
3. 若未处理，执行业务逻辑并持久化该 `processId` 已处理的记录。

```javascript
// 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();
}
```

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

### 并发限制

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

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

### 错误率

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

运维建议：

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

### 状态语义

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

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