Webhook Filter Reference

Webhook endpoints support filtering to control which events are sent. Filters are specified using array-based property syntax.

Filter Properties

Property	Type	Description
webhooks.endpoints.N.url	String	Webhook endpoint URL (required)
webhooks.endpoints.N.filters.categories	String	Comma-separated list of categories
webhooks.endpoints.N.filters.events	String	Comma-separated list of events
webhooks.endpoints.N.filters.nodeRole	String	Filter by node role
webhooks.endpoints.N.filters.app	String	Filter by application name
webhooks.endpoints.N.filters.sourceTypes	String	Filter by source types (rtmp, webrtc)
webhooks.endpoints.N.filters.streamPattern	String	Regex pattern for stream names

Example Configuration

# Send all events to primary endpoint
webhooks.endpoints.0.url=http://primary.example.com/webhook

# Send only PUBLISH events for WebRTC streams to secondary endpoint
webhooks.endpoints.1.url=http://analytics.example.com/webhook
webhooks.endpoints.1.filters.categories=PUBLISH
webhooks.endpoints.1.filters.sourceTypes=webrtc

Webhook Categories

Category	Events
CONNECT	connection-connect, connection-disconnect
PUBLISH	stream-published, stream-unpublished
SUBSCRIBE	stream-subscribed, stream-unsubscribed, video-started
WEBSOCKET	websocket-connect, websocket-disconnect
MEDIA	thumbnail-generated, video-saved
USER	Custom user-defined events

Webhook Events

Event	Category	Description
connection-connect	CONNECT	Client connected to server
connection-disconnect	CONNECT	Client disconnected from server
stream-published	PUBLISH	Stream started publishing
stream-unpublished	PUBLISH	Stream stopped publishing
stream-subscribed	SUBSCRIBE	Client started subscribing
stream-unsubscribed	SUBSCRIBE	Client stopped subscribing
video-started	SUBSCRIBE	Video playback started
websocket-connect	WEBSOCKET	WebSocket connection established
websocket-disconnect	WEBSOCKET	WebSocket connection closed
thumbnail-generated	MEDIA	Thumbnail image generated
video-saved	MEDIA	Video recording saved

Frame Extractor

Extracts JPEG frames from live streams and pushes them to a WebSocket endpoint. Builds on the thumbnail generation feature.

Server Properties (conf/red5.properties)

Property	Default	Description
thumbnails.active	false	Enable thumbnail / frame extraction
thumbnails.decode.all	false	Decode all frames (required for extraction)
thumbnails.websocket.endpoint		WebSocket URL to receive frames (e.g. ws://host:5080/ws/frames)
thumbnails.frequency	7	Extraction interval in seconds (0 = every frame)

Per-Stream Params (connection/query params)

Override server-level settings per stream using connection params or query params on the publish URL.

Param	Default	Description
thumbnails.active	false	Enable frame extraction for this stream
thumbnails.decodeAll	false	Decode all frames
thumbnails.websocketEndpoint		WebSocket URL to receive frames
thumbnails.frequency	7	Extraction interval in seconds (0 = every frame)

Per-Stream Example

ffmpeg -re -stream_loop -1 -i example.mp4 -c:v libx264 -c:a aac -f flv \
  "rtmp://RED5PRO_HOST/live/stream1?thumbnails.active=true&thumbnails.decodeAll=true&thumbnails.websocketEndpoint=ws://XENOSIM_HOST:5080/ws/frames&thumbnails.frequency=0"

WebSocket Binary Message Format

Offset	Length	Description
0	4 bytes	Metadata length (big-endian Int32)
4	N bytes	Metadata JSON (UTF-8): {"filename": "STREAM_TIMESTAMP.jpeg"}
4 + N	remaining	JPEG image data