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

# 交易 Webhook

> 接收签名订单与订阅生命周期事件。

使用 Webhook 作为订单或客户订阅状态变化的服务端信号。浏览器成功页面对买家有帮助，但不应
作为可靠的交付触发器。

## 设置接收地址

<Steps>
  <Step title="打开开发者设置">
    在 Business 个人菜单打开**开发者**，然后选择 **Webhook**。
  </Step>

  <Step title="添加 HTTPS 地址">
    输入用于接收所选交易事件的公开 HTTPS URL。
  </Step>

  <Step title="保存签名信息">
    在服务端配置中缓存已发布的 Ed25519 公钥；也可以保留端点 ID 用于跟踪配置。两者都不是签名密钥。
  </Step>

  <Step title="验证每个请求">
    请先使用原始请求体验证签名，再解析或处理事件。
  </Step>
</Steps>

## 交付规则

* 根据事件类型执行不同逻辑。
* 使用 `webhook-id` 请求头作为投递幂等键。
* 将金额、币种、产品和商户引用与你的记录核对。
* 使用 `subscription.*` 事件更新本地订阅状态；计划在周期结束时取消会产生
  `subscription.updated`，最终停止则产生 `subscription.ended`。
* 快速返回成功响应，把耗时任务放入队列。
* 接受重试和乱序投递。
* 不要因为旧事件晚到而把本地已支付订单退回**待处理**（`Pending`）。

<Warning>
  不要记录签名、API 密钥、完整客户付款信息、护照图片或提现账户信息。
</Warning>

<CardGroup cols={2}>
  <Card title="Webhook API 参考" icon="code" href="/zh/api-reference/endpoint/webhooks">
    查看公钥、签名契约、载荷、重试和幂等规则。
  </Card>

  <Card title="客户与订阅" icon="users" href="/zh/features/customers-and-subscriptions">
    了解订阅状态、计划取消和续费订单。
  </Card>
</CardGroup>