Hubfly spaceDocs
Console

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.

bash
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

TypedataSent when
input.connected, input.disconnectedinput, role, protocol, reason?An encoder connects to or leaves an input, on its primary or backup key.
input.failoverinput or channel, from, toPlayback switches between primary, backup and slate.
channel.live, channel.offlinechannelA channel goes on air or off air.
destination.connected, destination.failed, destination.stoppeddestination, error?, retry_in_ms?A restream connects, fails (on every failure) or stops.
recording.startedrecording, channelA recording starts.
recording.completedrecording, channel, storage_link, object_key, part, bytes, duration_ms, started_at, ended_at, register_assetA recording part is in Storage.
recording.failedrecording, channel, errorA recording fails.
clip.completed, clip.failedclip, channel, storage_link, object_key, bytes, duration_ms, name, error?A clip is saved, or fails.
schedule.fired, schedule.missed, schedule.failedschedule, fire_id, phase (start or end), at, error?A schedule phase runs, is skipped or fails.
processing.rejectedchannel or mixer, needed_mbps, available_mbpsAn output does not fit the processing cap.
speed.throttledegress_mbps, speed_mbpsThe server hit its speed cap. At most once a minute.
billing.blocked, billing.unblockedreasonThe server is paused for billing (balance, spend_cap or suspended), or resumes.
playlist.itemchannel, playlist, item, titleA 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

http
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"}}
HeaderValue
Hubfly space-Event-IdThe event's id. The same event can arrive more than once: use it to ignore repeats.
Hubfly space-Event-TypeThe event type, also in the body
Hubfly space-Delivery-IdThis delivery's id (whd_…), as shown in the delivery log
Hubfly space-Signaturet=<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:

TypeScript
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):

Go
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:

Go
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

  1. Split Hubfly space-Signature on commas. Take t and every v1 value; a header can carry more than one.
  2. Compute HMAC-SHA256 with the key = the whole secret string, whsec_ prefix included (UTF-8), over <t>.<raw body>. Encode it as lowercase hex.
  3. Accept when any v1 matches in constant time and t is within 300 seconds of now.
Python
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 new t.
  • Delivery log. Every attempt is kept for 7 days, with its status (delivered, failed or pending), HTTP status, error and next attempt. Open Deliveries on the webhook, or:
bash
hubfly stream webhooks deliveries acme-tv swh_hook0001

Answer 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.

bash
hubfly stream webhooks test acme-tv swh_hook0001
JSON
{"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

  • https only, 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

Webhooks cannot reach 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.

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top