Callbacks

Een callback is een uitgaande melding per verzoek die je aan een bestelling koppelt, zodat SuperSpace naar je URL POSTt op het moment dat het asynchrone werk van de bestelling klaar is — in plaats van dat jij de taak pollt. Je geeft de callback op wanneer je de bestelling plaatst; SuperSpace vuurt hem af zodra de taak van die bestelling een eindstatus bereikt (OK of FAILED).

Hoe het werkt

1. Je plaatst een bestelling met een callback-object (POST /api/orders of POST /api/orders/domain).
2. SuperSpace accepteert de bestelling (202 Accepted) en richt asynchroon in als een taak.
3. Wanneer de taak voltooid is (of mislukt), stuurt SuperSpace een HTTP POST naar de url van je callback.
4. Als je geen callback registreert, poll dan in plaats daarvan GET /api/tasks/{task-id}.

De callback is at-least-once: een levering die geen 2xx krijgt, wordt opnieuw geprobeerd (zie Levering en retries), dus je ontvanger moet idempotent zijn.

Een callback registreren

Voeg een callback-object toe aan de body van de bestelling. Het wordt op beide bestel-endpoints ondersteund:

• POST /api/orders — site-bestellingen
• POST /api/orders/domain — bestellingen voor domeinregistratie/-verhuizing

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

Wat SuperSpace verstuurt

Wanneer de taak klaar is, stuurt SuperSpace een POST naar je url:

• Headers: Authorization: <jouw authorization-waarde> (letterlijk; weggelaten als je er geen hebt opgegeven) en Accept: application/json.
• Body: JSON.

{
  "timestamp": 1727303593,
  "success": true,
  "data": "Site provisioned. Primary domain: example.com"
}

Levering en retries

Callbacks delen de uitgaande leveringslaag van SuperSpace (dezelfde die door billing-webhooks wordt gebruikt):

• Timeout: 30 seconden per poging.
• Succes: elke HTTP 2xx. Al het andere — inclusief een verbindingsfout of timeout — is een mislukte levering.
• Retries: een mislukte levering wordt opnieuw geprobeerd met backoff — elke 2 minuten gedurende de eerste 5 minuten, daarna elke 5 minuten tot 10 minuten oud, daarna elke 15 minuten — en SuperSpace geeft het 4 uur na de eerste poging op.
• Idempotentie: door retries kan dezelfde callback meer dan eens aankomen. Dedupliceer op timestamp (stabiel per logische gebeurtenis).

Bereikbaarheid testen

GET /api/webhooks/task

Retourneert het bron-IP dat SuperSpace voor je verzoek ziet, zodat je netwerkbereikbaarheid / allow-listing kunt bevestigen voordat je op een callback vertrouwt.

Een taakresultaat rapporteren

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

Dit is het endpoint dat een taak binnen SuperSpace als voltooid markeert — zo rapporteert de provisioning-infrastructuur een resultaat terug, en het posten van dat resultaat triggert je geregistreerde uitgaande callback. Het werkt de data van de taak bij, zet de status (OK / FAILED) en vuurt vervolgens de callback af.

Retourneert altijd 200, zelfs voor een onbekende task-ID. Idempotent: een herhaalde post met dezelfde data + success wordt op digest gededupliceerd en is een no-op.

Callbacks vs. billing-webhooks

Zie Billing Webhooks voor het mechanisme op planniveau.