> ## Documentation Index
> Fetch the complete documentation index at: https://doc2.payloco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 异步通知概述

> 介绍 Payloco Webhook 的订阅、投递重试、签名验证以及事件配置管理。

# Webhooks 概述

了解 Payloco Webhook 的工作原理，包括订阅、投递与重试、签名验证，以及在哪里设置或管理事件。

Webhooks 使 Payloco 能在你的 Payloco 账户发生事件时，向你的应用发送即时、实时的推送通知。理解 Webhook 的工作方式有助于你设计可靠的集成 。

## Webhook 如何工作

你通过注册通知 URL 并选择要接收的事件来创建 webhook 订阅。当这些事件中的某个在你的账户中发生时，Payloco 会向你的 URL 发送带 JSON 有效负载的 HTTP POST 请求。你的端点必须返回 200 状态码和以下报文体，以便 Payloco 确认投递成功：

```json theme={null}
{
  "code": "00000000",
  "message": "成功"
}
```

每个事件都有稳定的 `id`，因此你可以安全地处理重试并避免重复处理同一事件。有关创建订阅和配置端点的说明，请参阅 [监听 webhook 事件](./webhooks-signature)。

你也可以在 Payloco Web 应用中[查看并重新触发 webhook 事件](https://www.payloco.com/docs/developer-tools/webhooks/view-and-re-trigger-webhook-events.md)，检查投递状态（成功、排队或失败），并在停机后或调试时重新投递事件。

## 投递与可靠性

Payloco 将除返回 200 状态码且报文体 `code` 为 `00000000` 以外的任何响应，或超时，视为投递失败并进行重试。重试采用指数退避策略，直到你的端点返回 200 为止。

* **重复事件。** 你的端点可能会多次收到同一个事件。通过跟踪负载中的事件 `id` 实现幂等处理；同一事件在重试期间其 `id` 不会变化。
* **事件顺序。** Payloco 不保证事件按生成顺序投递。不要依赖投递顺序；如果需要排序，请使用负载中的 `notifyTime` 字段。

## 安全与验证

Payloco 对每个 webhook 请求进行签名，以便你可以验证该请求确实来自 Payloco 且未被篡改。签名使用请求时间戳和请求体计算 HMAC；你需要将计算出的值与请求头中的签名进行比较。每个订阅在 Payloco Web 应用中都有自己的 secret key。在解析或处理负载之前验证签名是关键的安全步骤。有关逐步说明和代码示例，请参阅 [检查 webhook 签名](https://www.payloco.com/docs/developer-tools/webhooks/listen-for-webhook-events#check-webhook-signatures.md)。

你的 webhook 端点应使用 HTTPS，并且服务器必须允许来自 Payloco webhook IP 地址的流量。生产环境和沙箱环境的 IP 列表请参阅 [监听 webhook 事件](https://www.payloco.com/docs/developer-tools/webhooks/listen-for-webhook-events#whitelist-ip-addresses.md)。

## 另请参阅

要设置或管理 webhook，你可以：

* 通过 [监听 webhook 事件](https://www.payloco.com/docs/developer-tools/webhooks/listen-for-webhook-events.md) 创建订阅、正确响应并验证签名。
* 通过 [查看并重新触发 webhook 事件](https://www.payloco.com/docs/developer-tools/webhooks/view-and-re-trigger-webhook-events.md) 在 Web 应用中检查事件并重新投递。