Register an event webhook

Registers an https endpoint that receives the workspace’s events from now on: the events about Sessions the registering member may read, of the event_types given (all when omitted). Returns its signing secret once; store it now. At most 10 per workspace. Requires automations:write and sessions:read; viewers cannot register. Each delivery is one event, POSTed as JSON (the event frame’s data from streamWorkspaceEvents), signed with Standard Webhooks headers: webhook-id (the event’s identity, the same on every retry, also sent as Idempotency-Key), webhook-timestamp (Unix seconds) and webhook-signature (v1, + base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<body>, keyed by the base64-decoded part of the endpoint’s whsec_ secret). Verify it with any Standard Webhooks library, or with a Reason Loop webhook that holds the secret. Answer 2xx within 10 seconds; anything else is retried with backoff (10 s doubling to 1 h), in order, and an endpoint failing for 3 days is disabled. Delivery is at least once: drop a repeated webhook-id.

_{Scope: automations:write}

POST /v3/organizations/{orgId}/event-webhooks

Register an event webhook

cURL

curl --request POST \
  --url https://api.reasonmachines.com/v3/organizations/{orgId}/event-webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "description": "<string>",
  "event_types": []
}
'

201

{
  "id": "<string>",
  "url": "<string>",
  "description": "<string>",
  "event_types": [
    "message.created"
  ],
  "status": "active",
  "disabled_reason": "<string>",
  "created_by": "<string>",
  "delivered_through": "<string>",
  "failures": 123,
  "failing_since": "<string>",
  "next_attempt_at": "<string>",
  "last_delivery_at": "<string>",
  "last_status": 123,
  "last_error": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "secret": "<string>"
}

Authorizations

Authorization · string · header · required

Your Reason API key from Settings › API keys. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, devices:read, devices:write, devices:use, computers:read, computers:write, ssh:write, knowledge:read, memory:read, memory:write, skills:read, skills:write, pages:read, pages:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. devices:write, devices:use, computers:read, computers:write, ssh:write, network:read and network:write are opt-in, excluded from default keys. computers:read lists visible cloud and connected computers without waking them or granting execution access. devices:read discovers local Device targets; devices:use separately consents to local execution, so a discover-and-run local workflow needs both. devices:write manages enrollment and device grants; computers:write creates or deletes cloud computers; ssh:write manages retained SSH access. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).

Path Parameters

orgId · string · required

Organization id or slug. Resolve it with GET /v3/self.

Body

application/json

url · string · required

The https URL that receives each event as a signed POST. Private and internal addresses are refused when delivering.

description · string | null

What the endpoint is for.

Maximum string length: 500

event_types · enum<string>[] | null

Only these event types; omit (or null) for every type.

Available options: message.created, turn.finished

Response

201

application/json

The new endpoint and its signing secret, shown only now.

id · string · required

url · string · required

The endpoint's URL: whole for its registering member and for workspace owners and admins, only its origin for other members.

description · string | null · required

event_types · enum<string>[] | null · required

Only these event types; omit (or null) for every type.

Available options: message.created, turn.finished

status · enum<string> · required

Available options: active, disabled

disabled_reason · string | null · required

Why it is disabled: by the API, or after failing for 3 days.

created_by · string · required

The member who registered it; it receives the events about Sessions this member may read.

delivered_through · string · required

The last event id delivered (or skipped as not visible or not wanted).

failures · integer · required

Failed deliveries in a row.

failing_since · string | null · required

next_attempt_at · string | null · required

last_delivery_at · string | null · required

last_status · integer | null · required

The HTTP status of the last attempt.

last_error · string | null · required

created_at · string · required

updated_at · string · required

secret · string · required

The whsec_ signing secret. Shown only in this response: store it now.