Callback notifications

When creating a static proxy purchase or renewal order, you may provide callback_url to receive a notification when the order reaches a terminal state.

Applicable APIs

Dynamic traffic purchases and dynamic sub-account creation do not support callbacks.

Request format

The Open API sends a POST request to callback_url:

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

Header	Description
`X-Pura-Signature`	Base64-encoded signature
`X-Pura-Signature-Timestamp`	Unix timestamp in seconds when the signature was generated

{
  "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"
}

Field	Type	Description
`request_no`	string	Request number supplied by the caller when creating the order
`order_no`	string	Order number
`order_type`	string	`STATIC_IP_PURCHASE` or `STATIC_IP_RENEWAL`
`status`	string	`COMPLETED` or `FAILED`
`finish_time`	string	Time when the order first entered a callback status, as GMT+8 ISO-8601. For a `FAILED` renewal order, this is the first time a failed result was observed; it does not mean that all resources have finished processing

Signature verification

Callbacks use RSA-SHA256 signatures. The signed content is the timestamp, one newline character, and the raw UTF-8 JSON request body, concatenated in that order:

Original X-Pura-Signature-Timestamp string + "\n" + raw JSON request body

Public key

The test and production environments use the same fixed public key:

Verification steps

Process the callback in this order:

Read both signature headers and the raw request-body bytes without parsing or reserializing them.
Confirm that X-Pura-Signature-Timestamp is a Unix timestamp in seconds and differs from the receiver's current time by no more than five minutes.
Verify the signed content described above with RSA-SHA256 and the fixed public key. Base64-decode X-Pura-Signature before verifying it.
Only after verification succeeds, parse the body and query order details by order_no. Even a valid callback cannot replace the order-detail query result.

Verify the exact raw request-body bytes you received. Regenerating JSON after parsing may change whitespace, line breaks, or field order and cause verification to fail. If either signature header is missing, the timestamp differs by more than five minutes, or signature verification fails, do not trigger a business query.

Delivery rules

Callbacks do not carry an API key or cookie. The receiver authenticates the callback with the signature headers above.
Any HTTP 2xx response from the receiver counts as successful delivery.
The receiver's response body is not used for business decisions.
Redirects are not followed, and HTTP 3xx is not considered success.
Connection failures, timeouts, certificate errors, and non-2xx responses are considered delivery failures.
At most one callback is attempted when an order first enters COMPLETED or FAILED. A failed attempt is not retried, and no second callback is attempted later.
In rare cases, the caller may receive the notification even though the sender cannot confirm delivery. Deduplicate callback processing by order_no.
When a renewal order first enters FAILED, some resources may still be PROCESSING. Later resource updates do not trigger another callback.
Disabling, revoking, or replacing the API key after order creation does not cancel a registered callback.

The receiver should respond within 10 seconds. The connection timeout is 3 seconds, and the total time from address validation to receiving response headers is limited to 10 seconds.

URL requirements

callback_url must meet all of the following requirements:

It is an absolute http or https URL.
Its total length does not exceed 2,048 characters.
It has a publicly reachable host.
It does not point to localhost, a private network, a link-local address, or a reserved address.
It does not depend on redirects.
If HTTPS is used, the certificate is valid and matches the domain name.

The address is checked when the order is created and again before delivery. An invalid address at creation time returns 400009.

Correct handling

A valid signature only proves that the notification came from a party holding the corresponding private key. The callback body is still not the sole source of the order result. After receiving and verifying a callback, use order_no to call the relevant detail API:

STATIC_IP_PURCHASE: Get static proxy purchase order details.
STATIC_IP_RENEWAL: Get static proxy renewal order details.

Continue polling if no callback is received. If a renewal order is FAILED, continue querying details until every resource is no longer PROCESSING. Do not provision resources or overwrite your final local state based only on the callback body.