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": "PARTIAL_SUCCESS",
  "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	Purchase orders: `SUCCESS`, `PARTIAL_SUCCESS`, or `FAILED`; renewal orders: `COMPLETED` or `FAILED`
`finish_time`	string	Time when the order first entered a callback status, as GMT+8 ISO-8601

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 production environment uses the following 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 the corresponding order list by order_no. Even a valid callback cannot replace the order-list 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 an applicable final status. 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.
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 list API:

STATIC_IP_PURCHASE: List static proxy purchase orders.
STATIC_IP_RENEWAL: List static proxy renewal orders.

Continue polling the corresponding order list if no callback is received. Stop polling a purchase order at SUCCESS, PARTIAL_SUCCESS, or FAILED, and a renewal order at COMPLETED or FAILED. If any result failed, query the latest static proxy resources and contact customer support. Do not provision resources or overwrite your final local state based only on the callback body.