Webhook Notifications

English | 中文

Webhook Notifications

LiveForge delivers HTTP webhook notifications for stream lifecycle events, signed with HMAC-SHA256 for security.

Configuration

notify:
  http:
    enabled: false
    endpoints:
      - url: "https://example.com/webhook"
        events: ["on_publish", "on_publish_stop"]
        secret: "your-hmac-secret"
        retry: 3
        timeout: 5s
      - url: "https://analytics.example.com/events"
        events: []           # Empty = all events
        secret: ""
        retry: 1
        timeout: 10s
  alive_interval: 10s
  websocket:
    enabled: false
    path: "/ws/notify"

Endpoint Fields

Field	Type	Default	Description
url	string	required	Webhook endpoint URL
events	[]string	[] (all)	Event filter. Empty list means all events are delivered.
secret	string	""	HMAC-SHA256 secret for signature verification. Empty means no signature.
retry	int	1	Number of delivery attempts
timeout	duration	5s	HTTP request timeout per attempt

Global Fields

Field	Type	Default	Description
alive_interval	duration	10s	Interval between alive events for active streams/publishers/subscribers

Events

Event	Trigger
on_publish	A publisher starts streaming
on_publish_stop	A publisher stops streaming
on_subscribe	A subscriber connects to a stream
on_subscribe_stop	A subscriber disconnects
on_stream_create	A new stream is created in the hub
on_stream_destroy	A stream is removed from the hub
on_publish_alive	Periodic heartbeat for an active publisher
on_subscribe_alive	Periodic heartbeat for an active subscriber
on_stream_alive	Periodic heartbeat for an active stream

Webhook Payload

Each webhook sends a JSON POST request:

{
  "event": "on_publish",
  "stream_key": "live/stream1",
  "protocol": "rtmp",
  "remote_addr": "192.168.1.100:54321",
  "timestamp": 1711468200,
  "extra": {}
}

Field	Type	Description
event	string	Event name
stream_key	string	Stream key (e.g., live/stream1)
protocol	string	Protocol used (e.g., rtmp, rtsp, webrtc)
remote_addr	string	Client IP and port
timestamp	int64	Unix timestamp when the event occurred
extra	object	Additional event-specific data

Alive Event Extra Fields

The on_publish_alive, on_subscribe_alive, and on_stream_alive events include additional statistics in the extra object:

Field	Type	Description
bytes_in	int64	Total bytes received
video_frames	int64	Total video frames received
audio_frames	int64	Total audio frames received
bitrate_kbps	float64	Current bitrate in kbps
fps	float64	Current video frames per second
uptime_sec	float64	Stream uptime in seconds

WebSocket Notifications

When websocket.enabled is true, clients can connect to the WebSocket endpoint at the configured path to receive real-time event notifications. Events are delivered as JSON messages with the same format as HTTP webhook payloads.

HMAC-SHA256 Signature Verification

When a secret is configured for an endpoint, every request includes an X-Signature header containing the hex-encoded HMAC-SHA256 of the JSON body.

Verification Example (Python)

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook handler:
body = request.get_data()
signature = request.headers.get("X-Signature", "")
if not verify_webhook(body, signature, "your-hmac-secret"):
    return "Unauthorized", 401

Retry Behavior

Failed deliveries are retried with exponential backoff:

Attempt	Wait Before Retry
1st retry	1 second
2nd retry	2 seconds
3rd retry	4 seconds
nth retry	min(2^(n-1), 30) seconds

The maximum backoff is capped at 30 seconds. If all retries are exhausted, the event is dropped.

Use Cases

• Analytics -- track publish/subscribe events for viewer counts and stream statistics
• Access control -- trigger external actions when streams start or stop
• Monitoring -- use alive events to detect stale streams or disconnected publishers
• Automation -- trigger recording, transcoding, or CDN cache invalidation on stream events