Ga naar inhoud

Callbacks

Een callback is een melding die je aan één bestelling koppelt. Als het asynchrone werk van de bestelling klaar is, stuurt CloudPress een POST naar je URL, zodat je de taak niet hoeft te pollen. Hij vuurt één keer, wanneer de taak een eindstatus bereikt (OK, FAILED of CANCELLED). Voor meldingen bij elke levenscyclusgebeurtenis onder een facturatieplan, zie billing-webhooks en de vergelijking hieronder.

Als je geen callback registreert, poll dan in plaats daarvan GET /api/tasks/{task-id}.


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
Params
  • callback: Object (optioneel) | Wordt afgevuurd wanneer de asynchrone taak van de bestelling voltooid is.
    • url: String (vereist) | Volledig gekwalificeerde HTTPS-URL die de POST ontvangt.
    • authorization: String (optioneel) | Wordt letterlijk als de Authorization-header op de callback meegestuurd. Geef de volledige waarde op — bijv. Bearer 12345, Token 12345, of een ruw 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"
        }
      }'

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"
}
Body-params
  • timestamp: Integer | Unix-epoch (seconden) waarop deze levering in de wachtrij is gezet. Stabiel over de retries van één levering heen, maar geen unieke gebeurtenissleutel — zie Levering en retries.
  • success: Boolean | true wanneer de taak eindigde op OK; false wanneer hij eindigde op FAILED of CANCELLED.
  • data: String | Het data-veld van de taak — dezelfde vrije resultaattekst die GET /api/tasks/{task-id} retourneert.

success: false betekent niet altijd dat de taak is mislukt

Een geannuleerde taak vuurt de callback ook af, en rapporteert "success": false — op de lijn niet te onderscheiden van een echte mislukking. De body bevat geen statusveld om ze uit elkaar te houden. Maakt dat onderscheid voor jou uit, lees de taak dan met GET /api/tasks/{task-id}, waar CANCELLED en FAILED aparte waarden zijn.


Levering en retries

Een timeout of geweigerde verbinding wordt nooit opnieuw geprobeerd

Alleen een levering die eindigt met een HTTP-reactie met een niet-2xx-status wordt opnieuw geprobeerd. Komt het verzoek helemaal niet tot stand (verbinding geweigerd, DNS- of TLS-fout, of de timeout van 30 seconden), dan wordt de levering één keer geprobeerd en daarna opgegeven. Poll voor alles wat je niet mag missen ook periodiek GET /api/tasks/{task-id}.

  • Timeout: 30 seconden per poging.
  • Succes: elke HTTP 2xx.
  • Retries: de eerste retry gaat 5 minuten na de oorspronkelijke poging uit, daarna elke 15 minuten.
  • Opgeven: de retries stoppen 4 uur na de eerste poging.
  • Idempotentie: dezelfde callback kan meer dan eens aankomen, en timestamp is geen veilige deduplicatiesleutel. De body bevat geen task-id, dus zet een order- of taakreferentie in de callback-url die je registreert en zorg dat je handler twee keer kan draaien.

Callbacks vs. billing-webhooks

Callback Billing-webhook
Geconfigureerd op Per verzoek, in het callback-object op een bestelling Het facturatieplan (admin-UI)
Scope De ene taak / bestelling waaraan hij was gekoppeld Levenscyclusgebeurtenissen van sites, cPanel-accounts en domeinen onder dat plan
Vuurt Eén keer, wanneer die taak OK / FAILED / CANCELLED bereikt Bij elke created / resized / registered / renewed / … gebeurtenis
Body { "timestamp", "success", "data" } (het taakresultaat) { "action", "site" }, { "action", "cpanel_account_link" } of { "action", "domain" }

Zie Billing Webhooks voor het mechanisme op planniveau.