Callbacks
A callback is a notification you attach to a single order. When the order's async work finishes, CloudPress sends a POST to your URL, so you don't have to poll the task. It fires once, when the task reaches a final state (OK, FAILED or CANCELLED). For notifications on every lifecycle event under a billing plan, see billing webhooks and the comparison below.
If you don't register a callback, poll GET /api/tasks/{task-id} instead.
Registering a callback
Add a callback object to the order body. Three endpoints accept it:
POST /api/orders— site ordersPOST /api/orders/domain— domain registration / transfer ordersPOST /api/cpanel_accounts— cPanel hosting account orders
Params
- callback: Object (optional) | Fired when the order's async task completes.
- url: String (required) | Fully-qualified HTTPS URL that receives the POST.
- authorization: String (optional) | Sent verbatim as the
Authorizationheader on the callback. Supply the full value — e.g.Bearer 12345,Token 12345, or a raw token.
curl -X POST https://my.cloudpress.com/api/orders \
-H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
-H "X-Auth-Account: $ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"order": { "plan": "basic", "term": "monthly" },
"callback": {
"url": "https://your-app.example.com/cloudpress/callback",
"authorization": "Bearer your-shared-secret"
}
}'
What CloudPress sends
When the task finishes, CloudPress sends a POST to your url:
- Headers:
Authorization: <your authorization value>(verbatim; omitted if you didn't supply one) andAccept: application/json. - Body: JSON.
{
"timestamp": 1727303593,
"success": true,
"data": "Site provisioned. Primary domain: example.com"
}
Body Params
- timestamp: Integer | Unix epoch (seconds) at which this delivery was queued. Stable across the retries of one delivery, but not a unique event key — see Delivery & retries.
- success: Boolean |
truewhen the task endedOK;falsewhen it endedFAILEDorCANCELLED. - data: String | The task's
datafield — the same free-form result text returned byGET /api/tasks/{task-id}.
success: false does not always mean the task failed
A cancelled task fires the callback too, and reports "success": false
— byte-for-byte indistinguishable from a genuine failure. The body carries
no status field to tell them apart. If the distinction matters to you, read
the task with GET /api/tasks/{task-id}, where CANCELLED and FAILED are
separate values.
Delivery & retries
A timeout or a refused connection is never retried
Only a delivery that completes with a non-2xx HTTP response is retried. If the request never completes (connection refused, DNS or TLS failure, or the 30-second timeout), the delivery is attempted once and then dropped. For anything you can't afford to miss, also poll GET /api/tasks/{task-id} periodically.
- Timeout: 30 seconds per attempt.
- Success: any HTTP
2xx. - Retries: the first retry is sent 5 minutes after the original attempt, then every 15 minutes.
- Giving up: retries stop 4 hours after the first attempt.
- Idempotency: the same callback can arrive more than once, and
timestampis not a safe de-duplication key. The body carries no task ID, so put an order or task reference in the callbackurlyou register and make your handler safe to run twice.
Callbacks vs. billing webhooks
| Callback | Billing webhook | |
|---|---|---|
| Configured on | Per request, in the callback object on an order |
The billing plan (admin UI) |
| Scope | The single task / order it was attached to | Site, cPanel-account & domain lifecycle events under that plan |
| Fires | Once, when that task reaches OK / FAILED / CANCELLED |
On every created / resized / registered / renewed / … event |
| Body | { "timestamp", "success", "data" } (the task result) |
{ "action", "site" }, { "action", "cpanel_account_link" } or { "action", "domain" } |
See Billing Webhooks for the plan-level mechanism.