Callbacks

Een callback is een uitgaande melding per verzoek die je aan een bestelling koppelt, zodat CloudPress 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; CloudPress vuurt hem af zodra de taak van die bestelling een eindstatus bereikt (OK, FAILED of CANCELLED).

Hoe het werkt

1. Je plaatst een bestelling met een callback-object (POST /api/orders, POST /api/orders/domain of POST /api/cpanel_accounts).
2. CloudPress accepteert de bestelling (202 Accepted) en richt asynchroon in als een taak.
3. Wanneer de taak voltooid is (of mislukt), stuurt CloudPress 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}.

Levering wordt opnieuw geprobeerd, maar is niet gegarandeerd. Een levering die met een niet-2xx-status wordt afgerond, wordt opnieuw geprobeerd, dus je ontvanger moet idempotent zijn — maar een levering die helemaal niet tot stand komt (verbinding geweigerd, timeout) wordt niet opnieuw geprobeerd en gaat verloren. Lees Levering en retries voordat je callbacks als enige signaal gebruikt.

Een callback registreren

Voeg een callback-object toe aan de body van de bestelling. Drie endpoints accepteren het:

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

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

Wat CloudPress verstuurt

Wanneer de taak klaar is, stuurt CloudPress 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 CloudPress (dezelfde die door billing-webhooks wordt gebruikt).

• Timeout: 30 seconden per poging.
• Succes: elke HTTP 2xx. Een afgeronde niet-2xx-reactie is een mislukte levering en wordt opnieuw geprobeerd. Een verbindingsfout of timeout niet — zie de waarschuwing hierboven.
• Retries: de eerste retry gaat 5 minuten na de oorspronkelijke poging uit, en daarna elke 15 minuten.
• Opgeven: de retries stoppen 4 uur na de eerste poging.
• Idempotentie: door retries kan dezelfde callback meer dan eens aankomen, dus je ontvanger moet idempotent zijn. timestamp is geen veilige deduplicatiesleutel — hij is stabiel over de retries van één levering heen, maar een taak die meer dan eens wordt afgerond (zowel de provisioning-job als een inkomende POST /api/webhooks/task/{task-id} starten een levering) levert een nieuwe timestamp op voor hetzelfde resultaat. De body bevat ook geen task-id, dus correleer op iets wat je zelf in de hand hebt: zet een order- of taakreferentie in de callback-url die je registreert, en zorg dat de handler twee keer kan draaien.

Bereikbaarheid testen

GET /api/webhooks/task

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

Op het pad van de cache-webhook bestaat een identieke test — GET /api/webhooks/cdn_cache.

Een taakresultaat rapporteren

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

Dit is het endpoint dat een taak binnen CloudPress 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.

Een CDN-cachepurge aanvragen

POST /api/webhooks/cdn_cache

Het inkomende endpoint waarmee de hostingcontainer van een site CloudPress vraagt om de CDN-cache van die site leeg te maken — bijvoorbeeld wanneer een WordPress-cacheplug-in na een publicatie de paginacache leegt. CloudPress zoekt de site op, opent een taak met de naam site.cache.cdn_purge en voert de purge asynchroon uit.

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

202 Accepted betekent geaccepteerd, niet "purge bevestigd" — de purge draait buiten de request om en probeert het intern opnieuw bij tijdelijke CDN-fouten. Een onbekende site, of een site zonder actieve CDN, is eveneens een geaccepteerde no-op ({"status":"accepted","noop":true}) in plaats van een fout, zodat de aanroeper "site weg" nooit van "leeggemaakt" hoeft te onderscheiden.

Omdat de aanroeper infrastructuur is en geen persoon, wordt de resulterende taak in de taakgeschiedenis van de site toegeschreven aan System.

Wil je als integrator de CDN-cache van een site leegmaken, gebruik dan de gewone per-site-endpoints — zie De cache leegmaken en Een cachelaag leegmaken.

Bereikbaarheid van de cache-webhook testen

GET /api/webhooks/cdn_cache

Dezelfde connectiviteitstest als GET /api/webhooks/task, op het pad van de cache-webhook.

Callbacks vs. billing-webhooks

Zie Billing Webhooks voor het mechanisme op planniveau.