Webhooks

Status: planned — not available yet. Webhooks are on the /v1 roadmap but are not implemented in the current dev preview. There is no endpoint to register a webhook today, and no events are delivered. This page describes the intended design so you can plan for it; the shapes below may change before it ships. Until then, subscribe to the studio's event stream (GET /v1/studios/{id}/events, Server-Sent Events) or poll GET /v1/studios/{id}/stream-status for live/offline state. See the Roadmap for phasing.

What webhooks will do

Instead of polling stream status, you'll register an HTTPS URL and receive a signed POST when something happens — starting with a studio going live or offline. This is the standard "don't poll, get pushed" pattern for stream-event integrations (go-live alerts, auto-posting, dashboards).

Planned event catalog

The first events map to the lifecycle the API already exposes as reads:

Event	Fires when	Phase
stream.live	A studio goes live	Phase 1 (with the write API)
stream.offline	A studio goes offline	Phase 1 (with the write API)
source.status_changed	A source's status changes	Phase 2
destination.status_changed	A destination's status changes	Phase 2
chat.message	A chat message is received	Phase 3

Planned delivery contract

When it ships, expect the platform's usual webhook discipline:

• Signed payloads. Each delivery carries an HMAC signature header so you can verify it came from TRaX and wasn't tampered with. Verify the signature before trusting the body.
• Delivery with retry. Failed deliveries are retried with backoff; your endpoint should be idempotent and return 2xx quickly.
• Registration + management. Register, list, and delete webhook subscriptions through the API, gated by a dedicated scope. That scope is not in the vocabulary yet, so no key minted today carries it.
• At-least-once semantics. Deduplicate on a delivery id; design your handler to tolerate the same event arriving more than once.

Until then: the event stream, or poll stream-status

The push channel that exists today is the studio's event stream, GET /v1/studios/{id}/events. It is Server-Sent Events over the same bearer auth: the first event is a snapshot, and a streamStatus event carries the same JSON stream-status returns whenever the studio goes live or offline. A reconnect with Last-Event-ID resumes, and a credential may hold at most five streams open at once (the sixth gets 429 with Retry-After). It needs a live connection, so it suits a dashboard or an app, not a server that wants to be called back.

The same live/offline signal is available as a plain read:

curl -sS "https://api.traxstreaming.live/v1/studios/<id>/stream-status" \
  -H "Authorization: Bearer sk_live_…"
# { "live": true, "encoderStreamId": "…", "liveStartedAt": "…", "mode": "cloud" }

Poll it on a sensible interval (respecting rate limits) and you have the same live/offline signal webhooks will push later — swapping to webhooks when they ship is then a small change.

Tell us if webhooks are what you need next — demand shapes the order things ship.