# Webhook 通知

Webhook 是发送至您 HTTPS 接收端的可选签名通知。仍可查询状态，使用 API 并不要求配置 Webhook。

## 我的 API 账户

请在 API 账户中启用接收端。必须使用公网 HTTPS/443，不支持重定向、查询参数或 URL 凭据。地址、启用状态或签名密钥变更会取消旧待发送事件，不补发历史操作。

仅观察受支持的新 API 操作，并非每个 HTTP 响应或网站订单。通知仅含安全标识与状态，不含 API 密钥或代理密码。timestamp 是本地 UTC 观测时间，每分钟运行的任务可能带来延迟。

## 事件类型

| 类型 | 状态 |
| --- | --- |
| `webhook.test` | `test` |
| `order.accepted` | `accepted` |
| `order.delivered` | `delivered` |
| `order.action_required` | `action_required` |
| `order.canceled` | `canceled` |
| `renewal.completed` | `completed` |
| `extra_login.operation.completed` | `completed` |
| `extra_login.operation.rejected` | `rejected` |
| `extra_login.operation.action_required` | `action_required` |
| `proxy_ip.operation.completed` | `completed` |
| `proxy_ip.operation.rejected` | `rejected` |
| `proxy_ip.operation.action_required` | `action_required` |
| `proxy_ip.authorization.revoked` | `revoked` |
| `residential_list.operation.completed` | `completed` |
| `residential_list.operation.rejected` | `rejected` |
| `residential_list.operation.action_required` | `action_required` |
| `auto_renewal.configuration.completed` | `completed` |

```json
{
    "id": "evt_0123456789abcdef0123456789abcdef",
    "type": "order.delivered",
    "timestamp": "2026-10-26T12:00:00+00:00",
    "api_version": "1",
    "data": {
        "account_id": 12345,
        "order_id": 12345,
        "number": "1000012345",
        "product": "proxy",
        "state": "delivered",
        "quantity": 1,
        "mode": null,
        "gb": null,
        "reason_code": null,
        "provider_live_check": false
    }
}
```

## 签名验证

使用独立 Webhook 密钥验证 webhook-id、webhook-timestamp 和 webhook-signature。去掉 whsec_ 前缀，Base64 解码密钥，对下方精确原始请求体格式计算 HMAC-SHA256，并进行恒定时间比较。时间戳容差为 300 秒。

```text
signed_content = webhook_id + "." + webhook_timestamp + "." + raw_body
webhook_signature = "v1," + Base64(HMAC_SHA256(decoded_secret, signed_content))
```

## 交付与重试

请按事件 ID 幂等处理。通知可能重复或乱序到达，接收后返回 2xx。最多尝试 7 次，延迟为 1 分钟、5 分钟、30 分钟、2 小时、6 小时和 24 小时。重试仅重发通知，不重复业务操作。

HTTP 2xx 表示接收成功。408/429/5xx 和临时网络错误可重试，其他 4xx 或重定向为永久失败。重试保留相同事件 ID 和请求体，使用新的签名时间戳。

---
[ARNPROXY API](https://docs.arnproxy.com/zh/api-v1/webhooks)