Create a webhook

Register an endpoint to receive a signed HTTP POST for every confirmed play on your monitored streams. No polling. Deliveries are settled before they are sent, so you get one event per airing and none for a detection we later discard (see Delivery timing). The response includes the signing secret once; store it to verify deliveries. Bundled with stream monitoring (no API credits).

Verifying deliveries

• Every POST carries Sonovault-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, "{t}.{rawBody}"). Recompute over the raw body and compare; reject if t is too old (replay protection).

• Also sent: Sonovault-Event-Id (stable across retries, so dedupe on it) and Sonovault-Event-Type.

• Return any 2xx to acknowledge. Non-2xx / timeouts are retried with exponential backoff (~10s → 6h, given up after 12 attempts); sustained failures auto-disable the endpoint.

Delivery timing

• A stream.play.started webhook arrives about 5 minutes after the play began, not the instant it is detected. started_at is always the real airing start, so the timeline you build is unaffected.

• The delay is deliberate. Deciding whether a detection is a real airing needs a few minutes of hindsight: a brief blip has to be seen ending, and a momentary mis-detection is only recognisable once the interrupted track resumes. Waiting means one webhook per airing, and none for a detection that never was.

• If you want the lowest possible latency instead, use the live SSE feed (GET /v1/streams/live), which pushes the moment a track is detected and may occasionally show a detection that later resolves differently.

Event payload

• stream.play.started - { id, type, created, data: { stream_id, started_at, track } }. (A track-end event isn't offered yet; there's no reliable end signal.)

• stream.offline - { id, type, created, data: { stream_id, at, reason } }. Sent when we detect a stream went down.

• stream.online - { id, type, created, data: { stream_id, at } }. Sent when a down stream recovers.

• track is the standard public track object (same shape as search results).