回调通知

创建静态代理购买订单或续费订单时，可以通过 callback_url 接收订单结束提醒。

适用接口

动态流量采购和动态子账号创建不提供回调。

请求格式

Open API 向 callback_url 发起 POST 请求：

Content-Type: application/json; charset=UTF-8
X-Pura-Signature: <BASE64_SIGNATURE>
X-Pura-Signature-Timestamp: <UNIX_TIMESTAMP_SECONDS>

请求头	说明
`X-Pura-Signature`	对签名结果进行 Base64 编码后的字符串
`X-Pura-Signature-Timestamp`	生成签名时的 Unix 秒级时间戳

{
  "request_no": "static-buy-20260824-001",
  "order_no": "PO1912345678901234567",
  "order_type": "STATIC_IP_PURCHASE",
  "status": "COMPLETED",
  "finish_time": "2026-08-24T15:35:00.000+08:00"
}

字段	类型	说明
`request_no`	string	创建订单时由调用方提供的请求号
`order_no`	string	订单号
`order_type`	string	`STATIC_IP_PURCHASE` 或 `STATIC_IP_RENEWAL`
`status`	string	`COMPLETED` 或 `FAILED`
`finish_time`	string	订单第一次进入回调状态的时间，GMT+8 ISO-8601；续费订单为 `FAILED` 时表示首次出现失败结果的时间，不表示全部资源均已处理结束

验签

回调使用 RSA-SHA256 签名。签名原文由时间戳、一个换行符和收到的原始 UTF-8 JSON 请求体依次拼接：

X-Pura-Signature-Timestamp 的原始字符串 + "\n" + 原始 JSON 请求体

验签公钥

测试环境和生产环境使用同一套固定公钥：

验签步骤

接收端应按以下顺序处理：

读取两个签名请求头和未经解析、未经重新序列化的原始请求体字节。
确认 X-Pura-Signature-Timestamp 是 Unix 秒级时间戳，并且与接收端当前时间的偏差不超过 5 分钟。
使用上方固定公钥，对上述签名原文执行 RSA-SHA256 验签。先对 X-Pura-Signature 做 Base64 解码，再校验签名。
只有验签通过后，才解析请求体并按 order_no 查询订单详情。即使验签成功，回调内容也不能替代详情查询结果。

必须对实际收到的原始请求体字节验签。解析后重新生成 JSON 会改变空格、换行或字段顺序，可能导致验签失败。任一签名请求头缺失、时间戳超出 5 分钟或签名校验失败时，不得触发业务查询。

接收规则

回调不携带 API Key 或 Cookie；接收端使用上述签名请求头完成验签。
接收地址返回任意 HTTP 2xx 即视为接收成功。
接收端的响应体不会参与业务判断。
重定向不会被跟随，HTTP 3xx 不视为成功。
连接失败、超时、证书错误或非 2xx 响应均视为失败。
每个订单在第一次进入 COMPLETED 或 FAILED 时最多发起一次回调；发送失败后不会重试，后续也不会发起第二次回调。
极端情况下，调用方可能已经收到通知，但发送结果未能被确认。接收端应按 order_no 去重。
续费订单第一次进入 FAILED 时，仍可能有资源处于 PROCESSING；这些资源后续更新不会再次触发回调。
订单创建后停用、吊销或更换 API Key，不会取消已经登记的回调。

接收端应在 10 秒内返回响应。连接等待上限为 3 秒，单次回调从地址检查到收到响应头的总等待上限为 10 秒。

地址要求

callback_url 必须满足以下条件：

为绝对 http 或 https 地址；
总长度不超过 2048 个字符；
必须具有可访问的公网主机；
不能指向本机、局域网、链路本地地址或保留地址；
不应依赖重定向；
如使用 HTTPS，证书必须有效且与域名匹配。

地址会在创建订单时检查，并在发送前再次检查。创建阶段地址不符合要求时返回 400009。

正确处理方式

验签通过只表示通知来自持有对应签名私钥的一方，回调内容仍不是订单结果的唯一依据。收到通知并验签通过后，应使用 order_no 调用相应详情接口再次查询：

STATIC_IP_PURCHASE：查询静态代理购买订单详情；
STATIC_IP_RENEWAL：查询静态代理续费订单详情。

如果没有收到回调，也应继续轮询订单。续费订单为 FAILED 时，应继续查询详情，直到所有资源都不再是 PROCESSING。不要依赖回调内容发放资源或覆盖本地最终状态。