Webhooks
A webhook sends a stream server's events to an HTTPS endpoint you run: a channel went live, a recording landed in Storage, a restream failed, a schedule fired. Each delivery is one event, signed with the webhook's secret.
Add a webhook
Add up to 10 webhooks per server under Playback & webhooks → Webhooks, with the API (POST …/stream/webhooks/create) or with the CLI. Managing webhooks needs stream:admin.
hubfly stream webhooks create acme-tv --url https://api.acme.com/hubfly/stream \
--events channel.live,channel.offline,recording.completed
# The whsec_ secret prints once: store it as HUBFLY_STREAM_WEBHOOK_SECRET
hubfly stream webhooks list acme-tv- Events: the event types to send. An empty list, or
["*"], sends every type. - Secret: a
whsec_…string, shown once when you create the webhook. Keep it on your server only.
Events
| Type | data | Sent when |
|---|---|---|
input.connected, input.disconnected | input, role, protocol, reason? | An encoder connects to or leaves an input, on its primary or backup key. |
input.failover | input or channel, from, to | Playback switches between primary, backup and slate. |
channel.live, channel.offline | channel | A channel goes on air or off air. |
destination.connected, destination.failed, destination.stopped | destination, error?, retry_in_ms? | A restream connects, fails (on every failure) or stops. |
recording.started | recording, channel | A recording starts. |
recording.completed | recording, channel, storage_link, object_key, part, bytes, duration_ms, started_at, ended_at, register_asset | A recording part is in Storage. |
recording.failed | recording, channel, error | A recording fails. |
clip.completed, clip.failed | clip, channel, storage_link, object_key, bytes, duration_ms, name, error? | A clip is saved, or fails. |
schedule.fired, schedule.missed, schedule.failed | schedule, fire_id, phase (start or end), at, error? | A schedule phase runs, is skipped or fails. |
processing.rejected | channel or mixer, needed_mbps, available_mbps | An output does not fit the processing cap. |
speed.throttled | egress_mbps, speed_mbps | The server hit its speed cap. At most once a minute. |
billing.blocked, billing.unblocked | reason | The server is paused for billing (balance, spend_cap or suspended), or resumes. |
playlist.item | channel, playlist, item, title | A playlist starts a new item. |
Webhook bodies use these field names exactly, in snake_case, as the stream server writes them. The Dashboard's event list (GET …/stream/events, kept for 7 days) shows the same events.
Payload and headers
POST /hubfly/stream HTTP/1.1
Content-Type: application/json
User-Agent: Hubfly space-Stream-Webhooks/1
Hubfly space-Event-Id: evt_9f8e7d6c
Hubfly space-Event-Type: channel.live
Hubfly space-Delivery-Id: whd_4k2m9q7x
Hubfly space-Signature: t=1767225600,v1=5f2b…
{"id":"evt_9f8e7d6c","type":"channel.live","at":"2026-01-01T00:00:00Z","tenant":"msi_abc12345","data":{"channel":"sch_main0001"}}| Header | Value |
|---|---|
Hubfly space-Event-Id | The event's id. The same event can arrive more than once: use it to ignore repeats. |
Hubfly space-Event-Type | The event type, also in the body |
Hubfly space-Delivery-Id | This delivery's id (whd_…), as shown in the delivery log |
Hubfly space-Signature | t=<unix seconds>,v1=<64 lowercase hex> |
The body is compact JSON: id, type, at (RFC 3339, UTC), tenant (the stream server's id, msi_…) and data.
Verify signatures
Verify every delivery before you act on it, against the raw request body. Parsing and re-encoding the JSON changes the bytes and breaks the signature. The SDKs refuse signatures more than 300 seconds old or ahead.
TypeScript, with @hubfly/streams (Node 18+, Bun, Deno and Workers). verifyWebhook resolves to true or false:
import { verifyWebhook } from "@hubfly/streams/server";
export async function POST(request: Request) {
const raw = await request.text();
const ok = await verifyWebhook(
process.env.HUBFLY_STREAM_WEBHOOK_SECRET!,
raw,
request.headers.get("Hubfly space-Signature"),
);
if (!ok) return new Response("invalid signature", { status: 400 });
const event = JSON.parse(raw);
// Skip event.id if you already handled it.
if (event.type === "channel.live") console.log("Live:", event.data.channel);
return new Response(null, { status: 204 });
}Go, with github.com/hubfly/hubfly-sdk/go/streams. The handler reads at most 1 MB, verifies the signature and answers 204, 400, or 500 when your function returns an error (so the delivery is retried):
http.Handle("/hubfly/stream", streams.WebhookHandler(
os.Getenv("HUBFLY_STREAM_WEBHOOK_SECRET"),
streams.WebhookOptions{},
func(r *http.Request, event streams.WebhookEvent) error {
switch event.Type {
case "channel.live", "channel.offline":
log.Printf("%s %s", event.Type, event.Data)
}
return nil
},
))To verify inside your own handler, call VerifyWebhook. It returns nil, or a *streams.WebhookError whose Reason is missing_signature, bad_signature or timestamp_out_of_tolerance:
body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
if err != nil {
http.Error(w, "read error", http.StatusBadRequest)
return
}
err = streams.VerifyWebhook(secret, body, r.Header.Get(streams.SignatureHeader), streams.WebhookOptions{})
var werr *streams.WebhookError
if errors.As(err, &werr) {
http.Error(w, werr.Reason, http.StatusBadRequest)
return
}Verify without the SDK
- Split
Hubfly space-Signatureon commas. Taketand everyv1value; a header can carry more than one. - Compute HMAC-SHA256 with the key = the whole secret string,
whsec_prefix included (UTF-8), over<t>.<raw body>. Encode it as lowercase hex. - Accept when any
v1matches in constant time andtis within 300 seconds of now.
import hashlib, hmac, time
def verify(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
t, signatures = None, []
for part in header.split(","):
key, _, value = part.strip().partition("=")
if key == "t":
t = value
elif key == "v1":
signatures.append(value)
if t is None or not t.isdigit() or abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, s) for s in signatures)Delivery and retries
- Success is any 2xx answer within 10 seconds. Redirects are not followed.
- Retries. A failed delivery is retried 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours later, about 8½ hours in all, then marked
failed. Each attempt is signed again with a newt. - Delivery log. Every attempt is kept for 7 days, with its status (
delivered,failedorpending), HTTP status, error and next attempt. Open Deliveries on the webhook, or:
hubfly stream webhooks deliveries acme-tv swh_hook0001Answer quickly and do slow work after you respond, so a busy handler does not turn into retries.
Test deliveries
Send test on a webhook, hubfly stream webhooks test or POST …/stream/webhooks/:webhookId/test sends one webhook.test event, signed the same way, and shows your endpoint's answer right away. The Dashboard sends it, not the media node, and it is not retried.
hubfly stream webhooks test acme-tv swh_hook0001{"id":"evt_test_…","type":"webhook.test","at":"…","tenant":"msi_…","data":{"webhook":"swh_hook0001","message":"This is a test delivery from the Hubfly space Dashboard."}}Allowed URLs
httpsonly, on port 443 or 8443, without a user name or password in the URL.- Every address the host resolves to must be public. Private, loopback, link-local, carrier-grade NAT, multicast, documentation, reserved and cloud metadata addresses are refused.
- Connecting gets 5 seconds and the TLS handshake 5 more, within the 10-second limit. Only the first 4 KiB of your answer is read.
Testing locally
localhost. Expose your local receiver with a public HTTPS tunnel, or use Send test and the delivery log against your deployed endpoint.See Webhooks and domains in the API reference.