Webhooks

A webhook endpoint receives a POST when something happens on your organization. It is the way to learn that a session went idle without holding a stream open.

Event types

Type	When
agent.created	An agent was created.
session.status_run_started	A turn started.
session.status_idled	The session went idle: its turn ended, or it waits on a tool's result.
session.status_terminated	The session was archived, or ended on an error it cannot recover from.
session.updated	An update set a new title, new metadata or a new agent. Clearing one sends none.
session.deleted	The session was deleted.
vault.created	A vault was created.
vault.archived	A vault was archived.
vault.deleted	A vault was deleted.
vault_credential.created	A credential was created.
vault_credential.archived	A credential was archived, alone or with its vault.
vault_credential.deleted	A credential was deleted.
vault_credential.refresh_failed	The token endpoint refused an mcp_oauth credential's refresh.

A session's webhook names are not its stream's: the stream's session.status_running and session.status_idle arrive as session.status_run_started and session.status_idled. Creating a session sends none of its own; its initial events start a turn, as a send does.

An endpoint with no type list receives all of them. Delivery is best effort. The change has already committed when the delivery starts, and coreloop backfills nothing.

The body

The body carries ids, not the resource. Read the resource from the API when you need its contents. A vault_credential event also carries its vault_id.

JSON

{
  "type": "event",
  "id": "whe_...",
  "created_at": "2026-09-22T11:04:07.913Z",
  "data": {
    "type": "session.status_idled",
    "id": "sesn_...",
    "organization_id": "org_...",
    "workspace_id": null
  }
}

Verifying

coreloop signs deliveries to the Standard Webhooks specification. Each request carries webhook-id, webhook-timestamp and webhook-signature. The secret shows once, when you register the endpoint. Verify with any Standard Webhooks library.

The id derives from what happened, so a retry, a re-run turn and a duplicate all carry the same one. Use it to deduplicate.
coreloop retries a failed delivery. It disables an endpoint that answers with a redirect or resolves to a private address.

Registering an endpoint

An endpoint belongs to the organization, not to this API. The route that creates one takes a signed-in owner.

Soon: a webhooks page in the dashboard.

Skills Reference