Billing webhooks

Billing webhooks are outbound notifications that CloudPress sends to your billing system when something happens to a service on a billing plan. They let an external biller — a plan that invoices customers outside Stripe (payment_method: none) — mirror lifecycle changes into its own books without polling the API.

Three resource types emit billing webhooks: sites (subscription lifecycle), cPanel accounts (subscription lifecycle), and domain registrations (registry lifecycle). All three go to the same plan endpoint and share the same envelope and delivery behavior; they differ only in the payload block (site, cpanel_account_link, or domain).

Configuration

Billing webhooks are configured per billing plan by an account or reseller administrator in the CloudPress admin UI. There is no public API endpoint to manage billing plans or their webhook settings.

Three fields on the plan control delivery:

A webhook fires only when both webhook_enabled is true and webhook_url is present. Otherwise the event is silently dropped — no retry, no error.

Delivery Semantics

• Method / body: HTTP POST with a JSON body to webhook_url.
• Headers: Authorization: <webhook_auth> (verbatim; omitted if blank) and Accept: application/json.
• Timeout: 30 seconds per attempt.
• Success: any HTTP 2xx. Anything else — including a connection failure or timeout — is treated as a failed delivery.
• Retries: failed deliveries are retried with backoff. The wait before the next attempt is derived from the age of the event: under 2 minutes old → wait 5 minutes; under 5 minutes old → wait 10 minutes; otherwise 15 minutes. In practice the first retry lands about 5 minutes after the event and later ones follow at 15-minute intervals. CloudPress gives up 4 hours after the event was emitted — the cut-off is measured from the event timestamp, not from the first attempt.
• Asynchronous: delivery happens out of band, after the originating work completes. It is not part of the triggering API call's HTTP response.

Events

Each delivery carries the event name in the top-level action field, and the resource block (site, cpanel_account_link, or domain) tells you which kind of event it is.

cPanel-account events carry a cpanel_account_link block and use the same four action names as sites. cPanel hosting is enabled per workspace, so a plan whose workspaces don't have it will simply never see these.

Domain-registration events carry a domain block. Billable events include a populated price; lifecycle-only events have price: null.

Payload

The POST body is a JSON object with two top-level keys: action (the event name) and a resource block — site for site events, cpanel_account_link for cPanel account events, domain for domain events.

Site payload

For site events the resource block is site (the same shape returned by 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/sftpuser/apps/adminsacc-dbe11dadb7eb9f9e/wordpress",
    "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" }
    }
  }
}

cPanel account payload

For cPanel-account events the resource block is cpanel_account_link. It is a deliberate subset of the site shape — it carries no CDN or infrastructure fields — plus "object": "cpanel_account_link" so receivers can route.

{
  "action": "created",
  "cpanel_account_link": {
    "object": "cpanel_account_link",
    "id": "12",
    "guid": "acme123",
    "cpanel_username": "acme123",
    "primary_domain": "example.com",
    "account": {
      "id": "16512906-c2b0-4c98-ac20-b1389838aa06",
      "name": "acme2"
    },
    "subscription": {
      "id": "9f2c1f7a-1b64-4a7e-8f31-2c6b0d3e5a41",
      "status": "active",
      "price": { "amount_cents": 5000, "term": "monthly" },
      "product": { "id": "cpanel_basic", "name": "Basic" }
    }
  }
}

Domain payload

For domain events the resource block is domain. It carries "object": "domain_registration" so receivers can route, and a price block that is populated for billable events and null otherwise.

{
  "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-account billing

When the owning account is a sub-account of a different billing account, the payload identifies both: account is set to the billing (parent) account and an extra sub_account block (inside the resource block) names the actual owner. This applies to all three payloads — site, cpanel_account_link and domain.

{
  "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": { "...": "..." }
  }
}

What does not trigger a webhook

Billing webhooks fire for the site, cPanel-account and domain events listed above. The following do not emit a billing webhook — even when paid:

• Mailbox hosting (Mailspace). No mail product emits a billing webhook. Reconcile it from the Subscriptions API.
• Restoring a soft-deleted site or cPanel account. Only the deleted event exists; recovery is silent.
• Backups, restores, cache, Shield, and other per-site task operations. Track these via task polling or a per-request completion callback.
• Order / invoice mechanics (charges, refunds, payment status). Billing webhooks describe service lifecycle, not invoice state; for order-level detail use the Orders API and the registrar processes.

Billing webhooks vs. task completion callbacks

CloudPress has two distinct push mechanisms. Don't confuse them:

See Callbacks for the per-request callback contract.