Webhook Subscriptions API

Overview

The Webhook Subscriptions API lets an organization register HTTP or HTTPS endpoints that receive signed JSON payloads when subscribed events occur. Subscriptions are scoped to an organization, and every delivery includes an X-Allternit-Signature header computed with HMAC-SHA256 over the payload. For details on verifying delivery signatures and example consumers, see the general Webhooks page.

Base URL

https://api.allternit.com/api/v1/beta/webhooks

For local development:

http://127.0.0.1:8013/api/v1/beta/webhooks

Authentication

All subscription routes require a valid bearer token and an active organization. See Authentication.

Subscription object

Field	Type	Description
`id`	string	Subscription UUID.
`org_id`	string	Owning organization.
`url`	string	HTTP or HTTPS endpoint that receives events.
`events`	string[]	Subscribed event types; `*` matches all events.
`active`	boolean	Whether the subscription is delivering events.
`created_at`	string	ISO 8601 timestamp.
`updated_at`	string	ISO 8601 timestamp.

Endpoints

Method	Path	Description
`GET`	`/api/v1/beta/webhooks`	List organization subscriptions.
`POST`	`/api/v1/beta/webhooks`	Create a subscription.
`GET`	`/api/v1/beta/webhooks/:id`	Get a subscription.
`PATCH`	`/api/v1/beta/webhooks/:id`	Update a subscription.
`DELETE`	`/api/v1/beta/webhooks/:id`	Delete a subscription.
`GET`	`/api/v1/beta/webhooks/:id/deliveries`	List delivery attempts.

Events

Event	Description
`agent.created`	An agent was created.
`agent.updated`	An agent was updated.
`agent.archived`	An agent was archived.
`session.created`	A session was created.
`session.event_created`	A new event was appended to a managed session.
`session.archived`	A session was archived.
`session.over_budget`	A session exceeded its budget.
`deployment.run_created`	A deployment run was created.
`deployment.run_updated`	A deployment run reached a terminal status.
`billing.credit_purchase`	A credit purchase completed.
`key.created`	An API key was created.
`key.revoked`	An API key was revoked.
`*`	Wildcard: subscribe to all events

Delivery makes up to 3 attempts per event. Connect errors, timeouts and 5xx responses are retried with a backoff of 5 s, then 20 s (base overridable with ALLTERNIT_WEBHOOK_RETRY_BASE_SECS); a 4xx response is not retried. Each attempt is recorded and visible through the deliveries endpoint. Only session.event_created and deployment.run_updated are documented with a payload here; check the deliveries list for the exact body of the others.

Create a subscription

POST /api/v1/beta/webhooks

Request body

Field	Type	Required	Description
`url`	string	Yes	HTTP or HTTPS endpoint URL.
`events`	string[]	Yes	Non-empty list of event types.
`secret`	string	Yes	Secret used to sign deliveries.

Example request

curl -X POST https://api.allternit.com/api/v1/beta/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/allternit",
    "events": ["session.event_created", "deployment.run_updated"],
    "secret": "whsec_01hqx8x7x7x7x7x7x7x7x7x"
  }'

Example response

{
  "subscription": {
    "id": "wh_01hqx8x7x7x7x7x7x7x7x7x",
    "org_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
    "url": "https://example.com/webhooks/allternit",
    "events": ["session.event_created", "deployment.run_updated"],
    "active": true,
    "created_at": "2026-08-13T18:00:00Z",
    "updated_at": "2026-08-13T18:00:00Z"
  }
}

List subscriptions

GET /api/v1/beta/webhooks

Returns subscriptions for the caller’s organization only.

Example response

{
  "subscriptions": [
    {
      "id": "wh_01hqx8x7x7x7x7x7x7x7x7x",
      "org_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
      "url": "https://example.com/webhooks/allternit",
      "events": ["session.event_created"],
      "active": true,
      "created_at": "2026-08-13T18:00:00Z",
      "updated_at": "2026-08-13T18:00:00Z"
    }
  ],
  "total": 1
}

Update a subscription

PATCH /api/v1/beta/webhooks/:id

Partial update. At least one field must be provided.

Request body

Field	Type	Description
`url`	string	HTTP or HTTPS endpoint URL.
`events`	string[]	Non-empty list of event types.
`secret`	string	New signing secret.
`active`	boolean	Enable or disable delivery.

Example request

curl -X PATCH https://api.allternit.com/api/v1/beta/webhooks/wh_01hqx8x7x7x7x7x7x7x7x7x \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "events": ["deployment.run_updated"]
  }'

Delete a subscription

DELETE /api/v1/beta/webhooks/:id

Returns 204 No Content on success.

List deliveries

GET /api/v1/beta/webhooks/:id/deliveries?status=failed&page=1&limit=50

Optional status filter: pending, delivered, or failed (anything else returns 400). page defaults to 1; limit defaults to 50 and is clamped to 1-100. The response holds deliveries, total, page, and limit. A subscription outside your organization returns 404.

Delivery payload

{
  "event": "session.event_created",
  "session_id": "sess_01hqx8x7x7x7x7x7x7x7x7x",
  "event_data": {
    "type": "thinking_delta",
    "delta": "hello"
  }
}

Error codes

Status	Code	Description
`201 Created`	—	Subscription created.
`200 OK`	—	Read or update succeeded.
`204 No Content`	—	Subscription deleted.
`400 Bad Request`	`url must be an http/https URL`	Invalid URL, empty events, missing secret, or no fields provided.
`400 Bad Request`	`organization required`	Caller has no active organization.
`401 Unauthorized`	—	Missing or invalid bearer token.
`404 Not Found`	`subscription not found`	Subscription missing or belongs to another organization.
`500 Internal Server Error`	—	Database or server error.

Platform API

Legal

Overview

Agency API (Preview)

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Overview

Base URL

Authentication

Subscription object

Endpoints

Events

Create a subscription

Request body

Example request

Example response

List subscriptions

Example response

Update a subscription

Request body

Example request

Delete a subscription

List deliveries

Delivery payload

Error codes

​Overview

​Base URL

​Authentication

​Subscription object

​Endpoints

​Events

​Create a subscription

​Request body

​Example request

​Example response

​List subscriptions

​Example response

​Update a subscription

​Request body

​Example request

​Delete a subscription

​List deliveries

​Delivery payload

​Error codes

​Related pages

Overview

Base URL

Authentication

Subscription object

Endpoints

Events

Create a subscription

Request body

Example request

Example response

List subscriptions

Example response

Update a subscription

Request body

Example request

Delete a subscription

List deliveries

Delivery payload

Error codes

Related pages