aimldocs
ReferenceApi

Org webhooks

your webhooks: endpoints, secrets, signatures, deliveries

List Webhooks

GET
/v1/webhooks

Authorization

bearer
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/webhooks"
{  "object": "list",  "data": [    {      "id": "wh_01J9ZK2K4Q7Q3M3QX1V0F1WH01",      "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",      "url": "https://hooks.acme.example/aiml",      "description": "billing",      "events": [        "topup.completed",        "topup.failed",        "invoice.issued"      ],      "status": "active",      "secret_hint": "whsec_…cd34",      "last_delivery_at": "2026-09-10T11:59:31Z",      "created_at": "2026-09-02T10:00:00Z"    }  ]}

Create Webhook

POST
/v1/webhooks

Authorization

bearer
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "https://hooks.acme.example/aiml",    "description": "billing",    "events": [      "topup.completed",      "topup.failed",      "invoice.issued"    ]  }'
{  "id": "wh_01J9ZK2K4Q7Q3M3QX1V0F1WH01",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",  "url": "https://hooks.acme.example/aiml",  "description": "billing",  "events": [    "topup.completed",    "topup.failed",    "invoice.issued"  ],  "status": "active",  "secret_hint": "whsec_…cd34",  "last_delivery_at": "2026-09-10T11:59:31Z",  "created_at": "2026-09-02T10:00:00Z",  "secret": "whsec_2f9e1a7c4b8d6e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f"}

List Webhook Events

GET
/v1/webhooks/events

Authorization

bearer
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/webhooks/events"
{  "object": "list",  "data": [    {      "name": "budget.threshold",      "description": "a key or project crossed a budget alert threshold"    },    {      "name": "budget.exhausted",      "description": "a hard budget paused a key or project"    },    {      "name": "topup.completed",      "description": "a credit top-up was booked"    },    {      "name": "invoice.issued",      "description": "an invoice or credit note was issued"    }  ]}

Get Webhook

GET
/v1/webhooks/{id}

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/webhooks/string"
{  "id": "wh_01J9ZK2K4Q7Q3M3QX1V0F1WH01",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",  "url": "https://hooks.acme.example/aiml",  "description": "billing",  "events": [    "topup.completed",    "topup.failed",    "invoice.issued"  ],  "status": "active",  "secret_hint": "whsec_…cd34",  "last_delivery_at": "2026-09-10T11:59:31Z",  "created_at": "2026-09-02T10:00:00Z"}

Update Webhook

PATCH
/v1/webhooks/{id}

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X PATCH "https://example.com/v1/webhooks/string" \  -H "Content-Type: application/json" \  -d '{    "status": "disabled"  }'
{  "id": "wh_01J9ZK2K4Q7Q3M3QX1V0F1WH01",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",  "url": "https://hooks.acme.example/aiml",  "description": "billing",  "events": [    "topup.completed",    "topup.failed",    "invoice.issued"  ],  "status": "disabled",  "secret_hint": "whsec_…cd34",  "last_delivery_at": "2026-09-10T11:59:31Z",  "created_at": "2026-09-02T10:00:00Z"}

Delete Webhook

DELETE
/v1/webhooks/{id}

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

curl -X DELETE "https://example.com/v1/webhooks/string"
Empty

Rotate Webhook Secret

POST
/v1/webhooks/{id}/rotate

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/webhooks/string/rotate"
{  "id": "wh_01J9ZK2K4Q7Q3M3QX1V0F1WH01",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",  "url": "https://hooks.acme.example/aiml",  "description": "billing",  "events": [    "topup.completed",    "topup.failed",    "invoice.issued"  ],  "status": "active",  "secret_hint": "whsec_…9a0b",  "last_delivery_at": "2026-09-10T11:59:31Z",  "created_at": "2026-09-02T10:00:00Z",  "secret": "whsec_9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"}

Test Webhook

POST
/v1/webhooks/{id}/test

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/webhooks/string/test"
{  "id": 105,  "webhook_id": "wh_01J9ZK2K4Q7Q3M3QX1V0F1WH01",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",  "event": "test.ping",  "event_id": "evt_01J9ZK2K4Q7Q3M3QX1V0F1EV01",  "payload": {    "hello": "world"  },  "status": "delivered",  "attempts": 1,  "response_code": 200,  "latency_ms": 143,  "attempt_log": [    {      "at": "2026-09-10T11:59:31Z",      "code": 200,      "latency_ms": 143    }  ],  "created_at": "2026-09-10T11:59:31Z",  "delivered_at": "2026-09-10T11:59:31Z"}

List Webhook Deliveries

GET
/v1/webhooks/{id}/deliveries

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

cursor?string
limit?integer
Rangevalue <= 200
Default50

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/webhooks/string/deliveries"
{  "object": "list",  "data": [    {      "id": 101,      "webhook_id": "wh_01J9ZK2K4Q7Q3M3QX1V0F1WH01",      "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",      "event": "topup.completed",      "event_id": "evt_01J9ZK2K4Q7Q3M3QX1V0F1EV01",      "payload": {        "topup_id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",        "credits_micro": 11916466      },      "status": "delivered",      "attempts": 1,      "response_code": 200,      "latency_ms": 143,      "attempt_log": [        {          "at": "2026-09-10T11:59:31Z",          "code": 200,          "latency_ms": 143        }      ],      "created_at": "2026-09-10T11:59:31Z",      "delivered_at": "2026-09-10T11:59:31Z"    }  ],  "next_cursor": ""}

Redeliver Webhook

POST
/v1/webhooks/{id}/deliveries/{delivery}/redeliver

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string
delivery*integer

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/webhooks/string/deliveries/0/redeliver"
{  "id": 106,  "webhook_id": "wh_01J9ZK2K4Q7Q3M3QX1V0F1WH01",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",  "event": "topup.completed",  "event_id": "evt_01J9ZK2K4Q7Q3M3QX1V0F1EV01",  "payload": {    "topup_id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",    "credits_micro": 11916466  },  "status": "queued",  "attempts": 0,  "attempt_log": [    {      "at": "2026-09-10T11:59:31Z",      "code": 200,      "latency_ms": 143    }  ],  "created_at": "2026-09-10T11:59:31Z"}