Skip to content
Dashboard
Theme
Theme

Sandbox event relay

Receive signed live events and sample events through the sandbox relay API.

View Markdown

The sandbox relay API streams events to a local development client without registering a public webhook endpoint. The API is implemented. ohauthcat init calls POST /v1/dev/init to register its callback (see the init quickstart). This guide describes the HTTP and WebSocket contract, not the CLI’s dev or events commands. See CLI credentials for the available sign-in commands.

Use a credential for the intended sandbox environment. Production environments return HTTP 403 sandbox_required. Keep credentials and the relay signing secret on your backend; a browser application must not receive them.

  • GET /v1/dev/relay requires webhooks:read and returns HTTP 101 for the WebSocket upgrade.
  • POST /v1/dev/trigger requires webhooks:write and returns HTTP 202 with a sample event descriptor.
  • POST /v1/dev/init requires environment:write and returns HTTP 200 with sandbox discovery and optional redirect registration.

The management API reference contains request schemas and refusal responses. These routes use the same environment-scoped credentials as other management operations.

Connect to /v1/dev/relay with WebSocket subprotocol ohauthcat.relay.v1. A normal HTTP request is not a relay connection. The server’s first JSON message has type: hello, the environment ID, a secret beginning with whsec_, heartbeat_seconds and max_session_seconds.

Each subsequent event message has type: event, id, event_type, test, body and signature. body is the raw webhook JSON encoded as a string. Verify those exact body bytes with the hello message’s relay secret and the signature value, using the webhook verification rules for OhAuthCat-Signature. The relay secret is distinct from a configured webhook endpoint’s secret. Do not parse and reserialize the body before verification. Deduplicate business effects by event ID.

The relay starts with events arriving after connection; it does not replay earlier events or guarantee catch-up across a disconnect. Use the Events API to recover recorded events. Sample events are not available through that API.

The server sends WebSocket pings; the client must respond with pong frames. The advertised session duration is one hour, with a 20-second heartbeat. Reconnect after a normal session expiry (close code 1000) or shutdown (1001). The relay accepts no client data messages; sending one closes it with 1008. Connection limits are five open relays per environment on each API server and 500 on that server in total. A refused connection returns HTTP 429 rate_limited with a five-second Retry-After; these limits apply to individual API servers.

Send POST /v1/dev/trigger with a JSON body containing a supported event type, for example organization.created. A missing or unknown type returns HTTP 400. HTTP 202 returns a DevEvent descriptor with id, object, type and created_at; it is not an acknowledgment from your local application.

Open the relay before triggering. A sample reaches the environment’s open relays with test: true. It never becomes a recorded event, a webhook endpoint delivery or a retryable delivery. Ordinary recorded events on the relay have test: false. Samples are limited to 20 per minute per environment; HTTP 429 includes Retry-After.

Discover the sandbox or register a redirect

Section titled “Discover the sandbox or register a redirect”

Call POST /v1/dev/init without a body to discover the environment and relay_path. Optionally send redirect_uri to register an exact redirect URI. HTTPS is allowed; sandbox also permits http://localhost. Credentials, fragments and wildcards in the URI are refused. An already registered exact URI is reused, with redirect_uri_created: false; a newly registered URI returns true.

This operation does not create an account, project, environment or application integration. Use the returned environment to check that your development client selected the intended sandbox.