Register a webhook endpoint

curl --request POST \
  --url https://api.get-exo.com/v1/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "eventTypes": [
    "<string>"
  ],
  "url": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/webhooks"

payload = {
    "eventTypes": ["<string>"],
    "url": "<string>"
}
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({eventTypes: ['<string>'], url: '<string>'})
};

fetch('https://api.get-exo.com/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "consecutiveFailures": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "disabled": true,
  "eventTypes": [
    "<string>"
  ],
  "id": "<string>",
  "secret": "<string>",
  "url": "<string>",
  "disabledReason": "<string>",
  "inactiveEventTypes": [
    "<string>"
  ],
  "lastDeliveryAt": "2023-11-07T05:31:56Z",
  "lastSuccessAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

POST

webhooks

curl --request POST \
  --url https://api.get-exo.com/v1/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "eventTypes": [
    "<string>"
  ],
  "url": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/webhooks"

payload = {
    "eventTypes": ["<string>"],
    "url": "<string>"
}
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({eventTypes: ['<string>'], url: '<string>'})
};

fetch('https://api.get-exo.com/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "consecutiveFailures": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "disabled": true,
  "eventTypes": [
    "<string>"
  ],
  "id": "<string>",
  "secret": "<string>",
  "url": "<string>",
  "disabledReason": "<string>",
  "inactiveEventTypes": [
    "<string>"
  ],
  "lastDeliveryAt": "2023-11-07T05:31:56Z",
  "lastSuccessAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

The response contains the signing secret. It is shown once, here, and is never retrievable again: store it before you close the response. Verify each delivery by recomputing HMAC_SHA256(secret, "<t>.<raw body>") and comparing it to the v1 value in the X-Exo-Signature header. The url must be https and must resolve to a public address: private, loopback, link-local, CGNAT, reserved and tunnelled ranges are rejected at registration and again at every delivery, and redirects are never followed. Unknown event types are rejected so a typo fails here rather than silently never firing; a subscribed type that no emitter publishes yet comes back in inactiveEventTypes for the same reason. An organization may register at most 20 endpoints (409 webhook_limit_reached beyond that). A retried Idempotency-Key returns the original registration but with the secret field replaced by a marker: the plaintext is never persisted anywhere, including the replay store. WHAT AN ENDPOINT RECEIVES. Registering does not widen what the key behind it can see. Events about the ORGANIZATION (insight.proposed, brain.trained) are delivered to every endpoint. Events about a PERSON (job.completed, basin.shifted, contradiction.detected, belief.superseded) are delivered only to endpoints registered by that person, mirroring the API, where another member’s job returns 404 and identity reads are self-or-admin. Events about a PROVISIONED SUBJECT are delivered to every endpoint, because any key in the organization can already read that subject’s data with X-Exo-Subject.

Authorization

This route requires the write scope. A missing or invalid credential returns 401 authentication_error. A valid credential without the scope returns 403 permission_denied, and the problem body names the exact scope required.

Headers

These are request conventions the contract does not declare as parameters, so they do not appear in the schema tables below.

Header	Applies	What it does
`X-Exo-API-Key`	Required	Your Exo API key, `exo_<env>_<token>`. `Authorization: Bearer exo_...` is accepted as an alternate.
`X-Exo-Subject`	Not applicable	This route is not subject-scoped.
`Idempotency-Key`	Honoured	Makes a retry safe. The same key with the same body replays the original response instead of acting twice. See Idempotency.
`X-Request-Id`	Response	Returned on every response, including `204`s. Quote it in a support request.

Success responses

Status	Meaning
`201`	Successful Response

Errors

Status	Code	When
`400`	`invalid_request`	Malformed request, for example an invalid cursor.
`401`	`authentication_error`	Missing or invalid credentials.
`403`	`permission_denied`	Missing scope, or an unprovisioned subject selector.
`404`	`not_found`	The resource does not exist, or is not visible to this caller.
`409`	`conflict`	A conflict with the current state of the resource.
`422`	`validation_error`	The request was understood but failed field validation.
`429`	`rate_limit_exceeded`	Rate limit exceeded. Retry after the Retry-After interval.
`503`	`service_degraded`	A dependency is temporarily unavailable. Safe to retry.

Beyond the shared statuses, this route can answer with webhook_limit_reached, idempotency_in_flight, idempotency_key_reuse. Every problem body names its own code, and the type URI always resolves to the matching page. Every error is an RFC 9457 application/problem+json body carrying a stable code, a requestId, and a suggestedAction where Exo has one. See Errors.

Notes

The signing secret is in this response and nowhere else. No route returns it again. Store it before you close the connection.
A replayed Idempotency-Key returns the registration with the secret redacted, not in the clear. The replay still proves the endpoint was created once.
The URL must be https and must resolve to a public address. Private, loopback, link-local, CGNAT, reserved and tunnelled ranges are rejected at registration and again at every delivery, and redirects are never followed.
Unknown event types are rejected here so a typo fails at registration rather than silently never firing.

Authorizations

X-Exo-API-Key

string

header

required

An Exo API key (exo_...) sent as the X-Exo-API-Key header.

Body

application/json

Body for POST /v1/webhooks.

eventTypes

string[]

required

Event types to subscribe to, or ['*'] for every event.

Required array length: 1 - 20 elements

url

string

required

HTTPS endpoint that will receive signed event deliveries.

Maximum string length: 2048

Response

Successful Response

Registration response: the ONLY place the signing secret is returned.

consecutiveFailures

integer

required

createdAt

string<date-time>

required

disabled

boolean

required

eventTypes

string[]

required

string

required

secret

string

required

The signing secret. Shown once, at registration, and never retrievable again -- not by a read route and not by an idempotent replay, which returns a marker in its place. Store it now; if it is lost, register a new endpoint.

url

string

required

disabledReason

string | null

inactiveEventTypes

string[]

Subscribed event types that no emitter publishes yet, so nothing will be delivered for them. The subscription is kept and starts delivering as soon as the emitter ships; this field exists so you never wait on an event silently.

lastDeliveryAt

string<date-time> | null

lastSuccessAt

string<date-time> | null

updatedAt

string<date-time> | null

List webhook endpoints

Inspect a webhook endpoint

⌘I

​Authorization

​Headers

​Success responses

​Errors

​Notes

Authorizations

Body

Response

Authorization

Headers

Success responses

Errors

Notes