Skip to content
Aether Docs

Create a webhook

POST
/api/v1/organizations/{orgID}/webhooks
curl --request POST \
  --url https://api.aetherplatform.cloud/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "example", "description": "example", "events": [ "example" ] }'

Registers a webhook endpoint. The server generates the signing secret and returns it in this response only — store it now; no later read includes it (rotate to obtain a new one). events is validated against the event-type catalog (see the Webhook schema). At most 10 webhooks per organization.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
orgID
required
string format: uuid

Organization UUID.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
url
required

Delivery endpoint. Must be https, without embedded credentials, and must not point at private or internal address ranges.

string
description
string
events
required

Event types to subscribe to (see the Webhook.events catalog), or exactly ["*"] for all of them.

Array<string>
Examplegenerated
{
  "url": "example",
  "description": "example",
  "events": [
    "example"
  ]
}

Responses

Section titled “Responses”

201

Section titled “201”

Webhook created. Includes the signing secret (shown once).

Media typeapplication/json
object
id
required
string format: uuid
org_id
required
string format: uuid
url
required

Delivery endpoint. Must be https, without embedded credentials, and must not point at private or internal address ranges.

string
description
required
string
events
required

Subscribed event types, validated against the catalog: cluster.created, cluster.ready, cluster.upgraded, cluster.degraded, cluster.deleted, node.replaced, usage.alert, invoice.generated, ticket.updated — or exactly ["*"] to subscribe to every catalog type. usage.alert fires once per budget threshold crossed in a month; its payload is {budget_eur, spend_eur, threshold_pct, billing_month}. invoice.generated fires at month close when an org’s invoice is generated; its payload is {invoice_id, amount_cents, currency, period_start, period_end}. ticket.updated fires whenever a support ticket is created, receives a new message, or changes status; its payload is {ticket_id, status, severity, category, last_message_author_type, updated_at} where last_message_author_type is tenant or provider for a message event and empty ("") for a status-only change.

Array<string>
enabled
required

Disabled webhooks receive no deliveries.

boolean
secret

Server-generated signing secret (whsec_<hex>). Returned once — present only in create and rotate-secret responses; list and get never include it.

string
created_at
required
string format: date-time
updated_at
required
string format: date-time
Examplegenerated
{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "url": "example",
  "description": "example",
  "events": [
    "example"
  ],
  "enabled": true,
  "secret": "example",
  "created_at": "2026-04-15T12:00:00Z",
  "updated_at": "2026-04-15T12:00:00Z"
}

401

Section titled “401”

Missing or invalid credentials.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ]
  }
}

409

Section titled “409”

Webhook limit reached for this organization (webhook_limit).

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ]
  }
}

422

Section titled “422”

Request validation failed.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ]
  }
}