Skip to content

Webhooks

ComputeStacks offers administrators a few different web hook options. All of these can be set in the admin under Settings. Integrations that use the User API can also receive callbacks when an action finishes.

To accept one of these web hooks, your system must return a status code 202 ACCEPTED. Otherwise, our system will retry the web hook (up to 5 times). The retry schedule is as follows:

  • First: One minute later
  • Second: 15 minutes later
  • Third - Fifth: Every hour.

Billing Events

These web hooks are triggered immediately when the event occurs, so depending on your environment, this could be many

  • New subscriptions (new orders)
  • Resizing
  • Cancelling subscription
  • Scaling container service
  • Automatic phase transitions

Billing Usage

This hook is for the aggregated billing usage that's processed on the last day of the month.

Here is an example output:

[
    {
        "billing_resource": {
            "billing_plan_id": 3,
            "external_id": "",
            "id": 12
        },
        "container_id": 65,
        "container_service_id": 53,
        "device_id": null,
        "external_id": null,
        "period_end": "2018-08-01 16:59:59 UTC",
        "period_start": "2018-06-30 23:00:00 UTC",
        "product": {
            "external_id": "",
            "id": 6,
            "name": "Container XS"
        },
        "qty": 762.0,
        "subscription_id": 59,
        "subscription_product_id": 175,
        "total": 3.048,
        "user": {
            "email": "user@example.com",
            "external_id": "1",
            "id": 8
        }
    }
]

API callbacks

Several User API actions accept an optional callback object, so an integration can learn when the work finishes instead of polling its event:

{
    "callback": {
        "url": "https://example.com/hooks/computestacks",
        "authorization": "Bearer 12345"
    }
}

When the action's event ends, whether it completed, failed, or was canceled, ComputeStacks sends a POST with a JSON body to url. authorization, if given, is sent as the Authorization header exactly as supplied. Any 2xx response accepts the callback; otherwise it is retried, at increasing intervals of up to 15 minutes, for up to 4 hours.

Payload
  • timestamp: Integer | When the callback was first queued, as seconds since epoch. It stays the same across retries.
  • event_id: Integer | The event this callback reports on.
  • status: String<completed,failed,cancelled>
  • code: String | A stable reason for a cancellation or failure that isn't the work itself going wrong, or null:
    • superseded: a deferred power action was replaced by a later power request for the same container.
    • node_maintenance: refused because the node is in maintenance.
    • node_offline: refused because the node is offline.
  • success: Boolean | true only when status is completed.
  • data: Array<String> | The event's detail lines.
Example 
{
    "timestamp": 1791460800,
    "event_id": 4102,
    "status": "cancelled",
    "code": "superseded",
    "success": false,
    "data": [
        "Superseded by a later restart request."
    ]
}

code is null for an ordinary failure and for a deferred power action that later ran, so match on code rather than on the text in data to tell a replaced or refused request from a real failure. A power action deferred during node maintenance calls back when it finally runs, not when it is accepted. See Refused and deferred actions.