# Sandbox event relay

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](/get-started/quickstart-init/)). This guide describes the HTTP and WebSocket contract, not the CLI's `dev` or `events` commands. See [CLI credentials](/get-started/cli/) for the available sign-in commands.

Use a credential for the intended sandbox environment. Production environments return HTTP 403 [`sandbox_required`](/errors/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](/reference/api/management/) contains request schemas and refusal responses. These routes use the same environment-scoped credentials as other management operations.

## Open the relay

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](/events/webhook-verification/) 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](/events/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`](/errors/rate_limited/) with a five-second `Retry-After`; these limits apply to individual API servers.

## Trigger a sample

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

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.
