Callbacks

A callback is a per-request, outbound notification you attach to an order so CloudPress POSTs to your URL the moment the order's async work finishes — instead of you polling the task. You supply the callback when you place the order; CloudPress fires it once that order's task reaches a terminal state (OK, FAILED, or CANCELLED).

How it works

1. You place an order with a callback object (POST /api/orders, POST /api/orders/domain, or POST /api/cpanel_accounts).
2. CloudPress accepts the order (202 Accepted) and provisions asynchronously as a task.
3. When the task completes (or fails), CloudPress sends an HTTP POST to your callback url.
4. If you don't register a callback, poll GET /api/tasks/{task-id} instead.

Delivery is retried but not guaranteed. A delivery that completes with a non-2xx status is retried, so your receiver must be idempotent — but a delivery that never completes at all (connection refused, timeout) is not retried and is lost. Read Delivery & retries before you build on callbacks as your only signal.

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

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

Delivery & retries

Callbacks share CloudPress's outbound delivery layer (the same one used by billing webhooks).

• Timeout: 30 seconds per attempt.
• Success: any HTTP 2xx. A completed non-2xx response is a failed delivery and is retried. A connection failure or timeout is not — see the warning above.
• Retries: the first retry is sent 5 minutes after the original attempt, and every 15 minutes after that.
• Giving up: retries stop 4 hours after the first attempt.
• Idempotency: retries mean the same callback may arrive more than once, so your receiver must be idempotent. timestamp is not a safe de-duplication key — it is stable across the retries of a single delivery, but a task that is finalized more than once (the provisioning job and an inbound POST /api/webhooks/task/{task-id} each trigger a delivery) produces a fresh timestamp for the same result. The body carries no task id either, so correlate on something you control: put an order or task reference in the callback url you register, and make the handler safe to run twice.

Testing reachability

GET /api/webhooks/task

Returns the source IP CloudPress sees for your request, so you can confirm network reachability / allow-listing before relying on a callback.

An identical probe exists on the cache-webhook path — GET /api/webhooks/cdn_cache.

Reporting a task result

POST /api/webhooks/task/{task-id}

This is the endpoint that marks a task complete inside CloudPress — it is how provisioning infrastructure reports a result back, and posting that result is what triggers your registered outbound callback. It updates the task's data, sets its status (OK / FAILED), and then fires the callback.

Always returns 200, even for an unknown task ID. Idempotent: a repeat post with the same data + success is de-duplicated by digest and is a no-op.

Requesting a CDN cache purge

POST /api/webhooks/cdn_cache

The inbound endpoint a site's own hosting container uses to ask CloudPress to purge that site's CDN cache — for example when a WordPress caching plugin flushes the page cache after a publish. CloudPress resolves the site, opens a task named site.cache.cdn_purge, and performs the purge asynchronously.

{ "cs_project_id": 4821, "mode": "paths", "paths": ["/", "/blog/*"] }

202 Accepted means accepted, not "purge confirmed" — the purge runs out of band and retries internally on transient CDN errors. An unknown site, or a site with no active CDN, is likewise an accepted no-op ({"status":"accepted","noop":true}) rather than an error, so the caller never has to tell "site gone" apart from "purged".

Because the caller is infrastructure rather than a person, the resulting task is attributed to System in the site's task history.

To purge a site's CDN cache as an integrator, use the ordinary per-site endpoints instead — see Purge the Cache and Purge a Cache Layer.

Testing cache-webhook reachability

GET /api/webhooks/cdn_cache

The same connectivity probe as GET /api/webhooks/task, on the cache-webhook path.

Callbacks vs. billing webhooks

See Billing Webhooks for the plan-level mechanism.