Webhooks

Outbound webhooks push platform events to a URL you control, so your backend learns about activity without polling. All operations are scoped to your tenant.

POST /api/v1/webhooks/<method>
X-API-Key: sk_your_key_here
Content-Type: application/json

No X-On-Behalf-Of here

Webhook endpoints belong to the tenant, not to an individual user, so these calls work with a bare secret key. That is different from most of the platform — see Acting as a user.

Concepts

Concept	Description
Endpoint	A URL you own that receives HTTP POSTs
Subscription	Binds an endpoint to a set of event types
Delivery	One attempt to POST one event to one endpoint

An endpoint on its own receives nothing — a subscription is what makes events flow to it.

One subscription per endpoint

Creating a second subscription on the same endpoint double-delivers every matching event. Keep exactly one.

There is no update-subscription route exposed today, so changing which events an endpoint receives means deleting the subscription and creating a replacement. Events published in the gap between those two calls are not delivered to that endpoint.

Event types

Conversation activity is published as these event types:

Event type	Emitted when
llm.generation_started	A generation run begins for a thread
llm.generation_completed	A generation run finishes
llm.message_published	A message is added to a thread's history
llm.tool_call_started	The model invokes a tool
llm.tool_call_completed	A tool invocation returns

Subscribe only to what you act on. llm.message_published and llm.generation_completed both fire on a normal assistant turn, so taking both means handling the same turn twice.

Where to next

Page	Covers
Endpoints & Subscriptions	Creating, listing, updating, and deleting
Deliveries	Delivery history, statuses, retries, and handler guidance

Related

• Webhook API Reference — All 9 endpoints with full schemas
• Authentication & API Keys — Issuing the secret key these calls need
• Notifications — For reaching people rather than systems