Billing webhooks

Billing webhooks zijn uitgaande notificaties die SuperSpace naar jouw factuursysteem stuurt wanneer er iets gebeurt met een dienst op een facturatieplan. Ze laten een externe biller — een plan dat klanten factureert buiten Stripe om (payment_method: none) — lifecycle-wijzigingen in zijn eigen boekhouding spiegelen zonder de API te pollen.

Twee resourcetypes versturen billing webhooks: sites (subscription-lifecycle) en domeinregistraties (registry-lifecycle). Beide gaan naar hetzelfde plan-endpoint en delen dezelfde envelope en hetzelfde leveringsgedrag; ze verschillen alleen in het payload-blok (site vs domain).

Configuratie

Billing webhooks worden per facturatieplan geconfigureerd door een account- of reseller- beheerder in de SuperSpace admin-UI. Er is geen publiek API-endpoint om facturatieplannen of hun webhookinstellingen te beheren.

Drie velden op het plan sturen de levering aan:

Een webhook wordt alleen afgevuurd wanneer zowel webhook_enabled true is als webhook_url aanwezig is. Anders wordt het event stilzwijgend genegeerd — geen retry, geen fout.

Leveringssemantiek

• Methode / body: HTTP POST met een JSON-body naar webhook_url.
• Headers: Authorization: <webhook_auth> (letterlijk; weggelaten indien leeg) en Accept: application/json.
• Timeout: 30 seconden per poging.
• Succes: elke HTTP 2xx. Al het andere — waaronder een verbindingsfout of timeout — wordt behandeld als een mislukte levering.
• Retries: mislukte leveringen worden 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.
• Asynchroon: de levering gebeurt buiten de band, nadat het oorspronkelijke werk is afgerond. Het maakt geen deel uit van het HTTP-antwoord van de triggerende API-aanroep.

Events

Elke levering draagt de eventnaam in het action-veld op het hoogste niveau, en het resource-blok (site of domain) vertelt je welk soort event het is.

Domeinregistratie-events dragen een domain-blok. Factureerbare events bevatten een gevulde price; lifecycle-only-events hebben price: null.

Payload

De POST-body is een JSON-object met twee keys op het hoogste niveau: action (de eventnaam) en een resource-blok — site voor site-events, domain voor domein-events.

Site-payload

Voor site-events is het resource-blok site (dezelfde shape die wordt teruggegeven door GET /api/sites/{site-id}).

{
  "action": "created",
  "site": {
    "id": "83426e2f-58f4-4e7e-99bc-b76b07a31574",
    "name": "adminsacc-dbe11dadb7eb9f9e",
    "primary_domain": "youthful-buck49235.example.com",
    "created_at": "2024-09-25T22:29:21.612Z",
    "updated_at": "2024-09-25T22:33:13.589Z",
    "location": "pdx",
    "region": "pdx01",
    "bunny_id": "1234567",
    "bunny_cname": "youthful-buck49235.b-cdn.net",
    "package": "pro",
    "php_version": "8.3",
    "domain_cname": "youthful-buck49235.b-cdn.net",
    "sftp_base_path": "/home/sites/83426e2f",
    "dunning_suspended": false,
    "account": {
      "id": "16512906-c2b0-4c98-ac20-b1389838aa06",
      "name": "acme2"
    },
    "subscription": {
      "id": "6d8bf084-ed11-4378-8531-ef584da08439",
      "status": "active",
      "created_at": "2024-09-25T22:33:13.581Z",
      "updated_at": "2024-09-25T22:33:14.333Z",
      "price": { "amount_cents": 5000, "term": "monthly" },
      "product": { "id": "pro", "name": "Pro" }
    }
  }
}

Domein-payload

Voor domein-events is het resource-blok domain. Het draagt "object": "domain_registration" zodat ontvangers kunnen routeren, en een price-blok dat gevuld is voor factureerbare events en anders null is.

{
  "action": "registered",
  "domain": {
    "id": "b2c3d4e5-6789-4abc-9def-0123456789ab",
    "object": "domain_registration",
    "name": "example.com",
    "status": "OK",
    "expires_at": "2026-09-25T00:00:00.000Z",
    "auto_renew": true,
    "privacy_protect": false,
    "tld": "com",
    "recovery_phase": null,
    "account": {
      "id": "16512906-c2b0-4c98-ac20-b1389838aa06",
      "name": "acme2"
    },
    "price": {
      "amount_cents": 1200,
      "currency": "usd",
      "term": "yearly"
    }
  }
}

Sub-accountfacturatie

Wanneer het bezittende account een sub-account van een ander facturatieaccount is, identificeert de payload beide: account wordt ingesteld op het facturatie- (parent-)account en een extra sub_account-blok (binnen het resource-blok) benoemt de werkelijke eigenaar. Dit geldt voor zowel site- als domain-payloads.

{
  "action": "resized",
  "site": {
    "id": "83426e2f-58f4-4e7e-99bc-b76b07a31574",
    "account":     { "id": "<billing-account-guid>", "name": "Parent Co" },
    "sub_account": { "id": "<owner-account-guid>",   "name": "Child Team" },
    "subscription": { "...": "..." }
  }
}

Wat geen webhook triggert

Billing webhooks worden afgevuurd voor de hierboven genoemde site- en domein-events. Het volgende verstuurt geen billing webhook — zelfs niet wanneer het betaald is:

• Back-ups, restores, cache, Shield en andere per-site taakoperaties. Volg deze via task polling of een per-request completion-callback.
• Order- / factuurmechaniek (charges, refunds, betaalstatus). Billing webhooks beschrijven de service-lifecycle, niet de factuurstatus; gebruik voor detail op orderniveau de Orders-API en de registrar-processes.

Billing webhooks vs. task completion callbacks

SuperSpace heeft twee verschillende push-mechanismen. Verwar ze niet:

Zie Callbacks voor het per-request-callbackcontract.