Skip to content

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 orders
  • POST /api/orders/domain — domain registration / transfer orders
  • POST /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 Authorization header 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) and Accept: 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 | true when the task ended OK; false when it ended FAILED or CANCELLED.
  • data: String | The task's data field — the same free-form result text returned by GET /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 timestamp is not a safe de-duplication key. The body carries no task ID, so put an order or task reference in the callback url you 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.