Skip to navigation
EndpointsAPI

Register a webhook endpoint

Create a webhook endpoint and receive its signing secret. The secret is returned exactly once in this response — store it immediately; it cannot be retrieved later.

Authentication: Supports API key and bearer token authentication.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

X-Organization-IDstring or nullOptional
Idempotency-KeystringOptional<=255 characters

A unique key (up to 255 printable ASCII characters, e.g. a UUID) that makes a retry of this request safe. Envoy stores the response for 24 hours; a retry with the same key and the same request returns it again with Idempotent-Replayed: true instead of running twice. The same key with a different request returns 422 idempotency_key_reused; while the first request is still running, 409 idempotency_key_in_progress. 5xx and 429 responses are not stored.

Request

This endpoint expects an object.
urlstringRequiredformat: "uri"1-2083 characters
HTTPS URL we will POST events to
event_typeslist of stringsRequired

Allowlist of event type names (e.g. [‘elp_test.scored’]). Must contain at least one entry.

descriptionstring or nullOptional<=500 characters
headersmap from strings to strings or nullOptional
Optional static headers we will include on every request to this endpoint.

Response

Successful Response
idstringformat: "^ep_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
organization_idstringformat: "^org_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
urlstring
descriptionstring or null
event_typeslist of strings
headersmap from strings to strings or null
statusenum

Endpoint lifecycle state.

DISABLED is reserved for automatic disable by the auto-disable job; PAUSED is explicitly paused and indicates intent to resume.

Allowed values:
disabled_reasonstring or null
created_atdatetime
updated_atdatetime
signing_secretstring

whsec_<base64> — store this; it is not retrievable later.

Errors

401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error