Skip to content

Callbacks

A callback is a per-request, outbound notification you attach to an order so SuperSpace 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; SuperSpace fires it once that order's task reaches a terminal state (OK or FAILED).

Callback vs. billing webhook

A callback is per request — it belongs to the single order you attach it to, and fires once. A billing webhook is plan-level — configured by an admin on the billing plan, it fires on every site/domain lifecycle event under that plan. Different mechanisms; see the comparison below.

How it works

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

The callback is at-least-once: a delivery that doesn't get a 2xx is retried (see Delivery & retries), so your receiver must be idempotent.

Registering a callback

Add a callback object to the order body. It is supported on both order endpoints:

  • POST /api/orders — site orders
  • POST /api/orders/domain — domain registration / transfer 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://control.superspace.nl/api/orders \
  -H "Authorization: Bearer $SUPERSPACE_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/superspace/callback",
          "authorization": "Bearer your-shared-secret"
        }
      }'

What SuperSpace sends

When the task finishes, SuperSpace 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) of the originating attempt — stable across retries, so usable as a delivery key.
  • success: Boolean | true when the task ended OK, false when it ended FAILED.
  • data: String | The task's data field — the same free-form result text returned by GET /api/tasks/{task-id}.

Delivery & retries

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

  • Timeout: 30 seconds per attempt.
  • Success: any HTTP 2xx. Anything else — including a connection failure or timeout — is a failed delivery.
  • Retries: a failed delivery is retried with backoff — every 2 minutes for the first 5 minutes, then every 5 minutes up to 10 minutes old, then every 15 minutes — and SuperSpace gives up 4 hours after the first attempt.
  • Idempotency: because of retries the same callback may arrive more than once. De-duplicate on timestamp (stable per logical event).

Testing reachability

GET /api/webhooks/task

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

Returned Params
  • ip_address: String

Reporting a task result

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

This is the endpoint that marks a task complete inside SuperSpace — 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.

Account Scope Required (X-Auth-Account). Not available via OAuth — this endpoint authenticates with a back-end API key (it is normally called by SuperSpace infrastructure, not by integrators).

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.

Params
  • data: Any (optional) | Appended to the task's data.
  • success: Boolean (required) | true → task OK; false → task FAILED.

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 All site & domain lifecycle events under that plan
Fires Once, when that task reaches OK / FAILED On every created / resized / registered / renewed / … event
Body { "timestamp", "success", "data" } (the task result) { "action", "site" } or { "action", "domain" }

See Billing Webhooks for the plan-level mechanism.