Events and webhooks

What this family does

GET /v1/events is an organization-scoped Server-Sent Events stream for a live view. The six webhook routes register endpoints that receive the same catalogue as signed HTTP deliveries, with retries and a delivery log you can inspect. The two transports carry the same event catalogue and apply the same reach rules, so a receiver sees the same set either way. The difference is durability: the stream does not replay, and webhooks retry.

Routes

Method	Path	Scope	What it does
`GET`	`/v1/events`	`read`	Stream organization events (SSE)
`GET`	`/v1/webhooks`	`read`	List webhook endpoints
`POST`	`/v1/webhooks`	`write`	Register a webhook endpoint
`DELETE`	`/v1/webhooks/{webhook_id}`	`write`	Delete a webhook endpoint
`GET`	`/v1/webhooks/{webhook_id}`	`read`	Inspect a webhook endpoint
`PATCH`	`/v1/webhooks/{webhook_id}`	`write`	Update a webhook endpoint
`POST`	`/v1/webhooks/{webhook_id}/test`	`write`	Send a test event to a webhook endpoint

Headers that apply here

Neither header is declared as an OpenAPI parameter, so neither appears in the generated schema tables.

Idempotency-Key makes a retry safe on POST /v1/webhooks. See Idempotency.

The shape of a call

curl -X POST https://api.get-exo.com/v1/webhooks \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/exo", "eventTypes": ["contradiction.detected"]}'

import httpx

response = httpx.post(
    "https://api.get-exo.com/v1/webhooks",
    headers={"X-Exo-API-Key": EXO_KEY},
    json={
        "url": "https://hooks.example.com/exo",
        "eventTypes": ["contradiction.detected"],
    },
)
secret = response.json()["secret"]  # shown once

const response = await fetch("https://api.get-exo.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-Exo-API-Key": process.env.EXO_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/exo",
    eventTypes: ["contradiction.detected"],
  }),
});
const { secret } = await response.json(); // shown once

The response:

{
  "id": "3b0f1c2e-6a44-4c1f-9f2b-0d5a7c8e1042",
  "url": "https://hooks.example.com/exo",
  "eventTypes": ["contradiction.detected"],
  "inactiveEventTypes": [],
  "disabled": false,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "lastDeliveryAt": null,
  "lastSuccessAt": null,
  "createdAt": "2026-07-14T09:12:03Z",
  "updatedAt": null,
  "secret": "whsec_5f2a9c1e7b40d83a6cf1e29b47d05a8c3e6f1b24d97"
}

Traps

The stream does not replay. Last-Event-ID is accepted so resuming clients do not error, and it is ignored. A client that must not miss a transition should use a webhook. Five concurrent streams per organization. The sixth is 429 too_many_streams with Retry-After. The signing secret is shown once. It is in the registration response and nowhere else. A replayed Idempotency-Key returns it redacted, not in the clear. Endpoints auto-disable after 8 consecutive failures. Re-enable with PATCH {"disabled": false}, which also clears the failure streak. Payloads are thin by design. A delivery carries identifiers and small scalars, never node content. Read the object back through the API, so your receiver sees exactly what your credentials allow.

API reference

Base URL, authentication, and the conventions every route shares.

Errors

The problem envelope and the full code catalogue.

​What this family does

​Routes

​Headers that apply here

​The shape of a call

​Traps

​Related