Webhooks

Included with the Red5 Pro live webapp is a webhook functionality that can call a custom REST endpoint to push various events. Additionally, user defined webhooks can be implemented in custom webapps.

Webhooks

Webhook events are available in the following categories: CONNECT, PUBLISH, SUBSCRIBE, WEBSOCKET and USER. The following sections describe the available webhook events in each category.

CONNECT

Webhooks in the CONNECT category are called when a client connects or disconnects.

connection-connect is called on connection
connection-disconnect is called on disconnection

PUBLISH

Webhooks in the PUBLISH category are called when a stream is published or unpublished.

stream-published is called on publish
stream-unpublished is called on unpublish

Webhooks in the SUBSCRIBE category are called when a subscriber stream begins and ends.

stream-subscribed is called when a new subscriber joins
stream-unsubscribed is called when a subscriber leaves

WEBSOCKET

Webhooks in the WEBSOCKET category are called when a websocket connects or disconnects.

websocket-connect is called on websocket connection
websocket-disconnect is called on websocket disconnection

USER

Custom webhooks can be placed in any of the above categories or in the USER category. When implementing a custom webhook in a custom webapp, use the WebhookEvent.USER category to place the webhook in the USER category.

Webhook Data

The payload of a webhook event contains five fields:

{
    "event": "connection-connect",
    "guid": "6NEETIQ1YJIFL",
    "username": "foo",
    "userAgent": "Mozilla/5.0 ... Chrome/117.0.0.0 ...",
    "clusterNodeType": "TYPE_AUTO"
}

event: The name of the webhook event (as defined above).
guid: The GUID for the event. The meaning of this field varies depending on the category:

CONNECT events use the connection session ID.
PUBLISH and SUBSCRIBE events use the stream's unique path and name (e.g., live/stream1).
WEBSOCKET events use the websocket session ID.

username: The username (if any) supplied for Simple Authentication.
useragent: The client-supplied User-Agent string.
clusterNodeType: The type of cluster node where the webhook originated: TYPE_ORIGIN, TYPE_EDGE, TYPE_MIXER, TYPE_RELAY, TYPE_TRANSCODER, or -- for standalone nodes -- TYPE_OFF or TYPE_AUTO.

When are Webhook Events fired?

Any given type of connection will only fire certain webhook events. It is important to know when to expect which events.

	CONNECT	DISCONNECT	PUBLISH	UNPUBLISH	SUBSCRIBE	UNSUBSCRIBE	WS_CONNECT	WS_DISCONNECT
Pub (WHIP)	name, agent	name, agent	name, agent	name, agent	n/a	n/a	n/a	n/a
Sub (WHEP)	name, agent	name, agent	n/a	n/a	name, agent	name, agent	n/a	n/a
Pub (RTC)	name, agent	name, agent	name, agent	name, agent	n/a	n/a	name, agent	name, agent
Sub (RTC)	name, agent	name, agent	n/a	n/a	name, agent	name, agent	name, agent	name, agent
Pub (RTMP)	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a
Sub (RTMP)	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a

CONFIGURATION

This feature is configured in the server side live webapp and must be applied to all streaming nodes (Origins, Edges, Mixers, Relays, and Transcoders) that are expected to provide events.

Configure the webapp by editing {Red5Pro}/webapps/live/WEB-INF/red5-web.properties and updating the webhooks.endpoint configuration with the URI for the webhook to call:

webapp.contextPath=/live
webapp.virtualHosts=*

# Optional endpoint like http://localhost:8001/webhook for webhook events
# Leave empty if not used
webhooks.endpoint=https://localhost:8001/webhook

Note: If the feature is not used, webhooks.endpoint must be left empty. It is important not to comment or remove this configuration line as that would prevent the live application from working correctly.

Muting Webhooks

By default the webhook system will call the configured endpoint for every category of webhooks. To only receive a subset of the webhooks, the muting function can be used. To mute a webhook, add the category to the webhooks.muteCategories configuration. For example, to mute the all webhooks except CONNECT, add the following configuration:

webhooks.muteCategories=PUBLISH, WEBSOCKET, USER

Webhook Example Calls

This example shows the series of webhook events about a publisher and subscriber throughout their connections' lifecycles. In reality these webhook events are interleaved but here they are separated to show each series of events individually.

These examples used RTC (rather than WHIP/WHEP), and thus you will see WebSocket events.

Publisher

{"event":"websocket-connect","guid":"0","username":"foo","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36","clusterNodeType":"undefined"}
{"event":"connection-connect","guid":"6NEETIQ1YJIFL","username":"foo","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36","clusterNodeType":"TYPE_AUTO"}
{"event":"stream-published","guid":"live/stream1","username":"foo","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36","clusterNodeType":"TYPE_AUTO"}
{"event":"websocket-disconnect","guid":"6NEETIQ1YJIFL","username":"foo","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36","clusterNodeType":"TYPE_AUTO"}
{"event":"connection-disconnect","guid":"6NEETIQ1YJIFL","username":"foo","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36","clusterNodeType":"TYPE_AUTO"}
{"event":"stream-unpublished","guid":"live/stream1","username":"foo","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36","clusterNodeType":"TYPE_AUTO"}

Subscriber

{"event":"websocket-connect","guid":"3","username":"baz","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/118.0","clusterNodeType":"undefined"}
{"event":"connection-connect","guid":"GYFFJTJEVCEBX","username":"baz","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/118.0","clusterNodeType":"TYPE_AUTO"}
{"event":"stream-subscribed","guid":"live/stream1","username":"baz","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/118.0","clusterNodeType":"TYPE_AUTO"}
{"event":"websocket-disconnect","guid":"GYFFJTJEVCEBX","username":"baz","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/118.0","clusterNodeType":"TYPE_AUTO"}
{"event":"connection-disconnect","guid":"GYFFJTJEVCEBX","username":"baz","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/118.0","clusterNodeType":"TYPE_AUTO"}
{"event":"stream-unsubscribed","guid":"live/stream1","username":"baz","userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/118.0","clusterNodeType":"TYPE_AUTO"}

Webhooks

Webhooks

CONNECT

PUBLISH

SUBSCRIBE

WEBSOCKET

USER

Webhook Data

When are Webhook Events fired?

CONFIGURATION

Muting Webhooks

Webhook Example Calls

Publisher

Subscriber

Red5 Pro Platform