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, 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 webhooks:manage scope. The scope vocabulary already lists webhooks:manage so keys you mint now stay valid when this lands.
• At-least-once semantics. Deduplicate on a delivery id; design your handler to tolerate the same event arriving more than once.

Until then: poll stream-status

The live/offline signal is available today as a read:

curl -sS "https://api-dev.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.