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`

application/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 秒。

HMAC-SHA256

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 和请求体，使用新的签名时间戳。