OpenVidu Webhook

OpenVidu offers a WebHook service to receive events in your application server.

Enable Webhook service
How your WebHook endpoint should be
Format of the WebHook events
OpenVidu WebHook events

Enable Webhook service 🔗

The following configuration properties allow enabling and configuring OpenVidu Webhook service:

OPENVIDU_WEBHOOK: set it to true to enable webhook service.
OPENVIDU_WEBHOOK_ENDPOINT: configure the HTTP endpoint where OpenVidu Server will send the POST messages with session events. This property is mandatory if OPENVIDU_WEBHOOK is set to true.
OPENVIDU_WEBHOOK_HEADERS: an array of HTTP headers that OpenVidu Server will append to each POST message. For example, you may configure HTTP authorization with this property. By default this property is an empty array (no headers)
OPENVIDU_WEBHOOK_EVENTS: an array with the type of events you want OpenVidu Server to send to your webhook. By default all available events are enabled.

For example, the configuration properties below will launch OpenVidu Server with webhook service enabled, sending session events to an HTTP endpoint located at http://12.34.56.78:5000/my_webhook, passing a Basic Auth header and sending only sessionCreated, sessionDestroyed and recordingStatusChanged events.

OPENVIDU_WEBHOOK=true
OPENVIDU_WEBHOOK_ENDPOINT=http://12.34.56.78:5000/my_webhook
OPENVIDU_WEBHOOK_HEADERS=["Authorization: Basic T1BFTlZJRFVBUFA6TVlfU0VDUkVU"]
OPENVIDU_WEBHOOK_EVENTS=["sessionCreated","sessionDestroyed","recordingStatusChanged"]

How your WebHook endpoint should be 🔗

The HTTP endpoint you configure in property OPENVIDU_WEBHOOK_ENDPOINT must meet two criteria:

Should listen to HTTP POST requests
Should return a 200 success response upon each POST request

If OpenVidu Server cannot successfully send the HTTP POST messages to the endpoint and do not receive a 200 success as response, it will log one error message for each attempt. No further action will be taken.

Format of the WebHook events 🔗

You can retrieve the WebHook events information from the body request of the HTTP POST operation. It is available in JSON format, always following this structure:

{
    "event": "EVENT_TYPE",
    "timestamp": 1234567890,
    "prop1": "value1",
    "prop2": "value2",
          ...
    "propN": "valueN"
}

event: the type of event.
timestamp: a number with the time when the event was registered in UTC milliseconds.
prop1, prop2 ... propN : custom properties for each specific event. Their name and type differ from each other.

sessionCreated 🔗

Recorded when a new session has been created. This event will be triggered at the end of a successful call to the REST API method to initialize a session (REST API, openvidu-java-client, openvidu-node-client).

{
    "event": "sessionCreated",
    "timestamp": 1601394690713,
    "sessionId": "ses_Jd8tUyvhXO"
}

Property	Description	Value
`event`	Event type	`sessionCreated`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`sessionId`	Session for which the event was triggered	A String with the session's unique identifier

sessionDestroyed 🔗

Recorded when a session has finished.

{
    "event": "sessionDestroyed",
    "timestamp": 1601395365656,
    "sessionId": "ses_Jd8tUyvhXO",
    "startTime": 1601394690713,
    "duration": 674,
    "reason": "lastParticipantLeft"
}

Property	Description	Value
`event`	Event type	`sessionDestroyed`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`sessionId`	Session for which the event was triggered	A String with the session's unique identifier
`startTime`	Time when the session started	A Number (UTC milliseconds)
`duration`	Total duration of the session	A Number with the duration in seconds
`reason`	Why the session was destroyed (complete description)	A String with one of these possible values `"lastParticipantLeft"` `"sessionClosedByServer"` `"mediaServerDisconnect"` `"nodeCrashed"` `"openviduServerStopped"` `"automaticStop"`

participantJoined 🔗

Recorded when a user has connected to a session.

{
    "event": "participantJoined",
    "timestamp": 1601394715606,
    "sessionId": "ses_Jd8tUyvhXO",
    "connectionId": "con_EIeO06zgMz",
    "location": "Berlin, Germany",
    "ip": "37.122.145.190",
    "platform": "Chrome 85.0.4183.121 on Linux 64-bit",
    "clientData": "Mike",
    "serverData": "{'user': 'client1'}"
}

Property	Description	Value
`event`	Event type	`participantJoined`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`sessionId`	Session for which the event was triggered	A String with the session's unique identifier
`connectionId`	Identifier of the participant	A String with the participant's unique identifier
`location`	Geo location of the participant PRO	A String with format `"CITY, COUNTRY"` (or `"unknown"`)
`ip`	The IP of the participant, as seen by OpenVidu Server	A String with the participant's IP
`platform`	Complete description of the platform used by the participant to connect to the session	A String with the platform description
`clientData`	Metadata associated to this participant from the client side. This corresponds to parameter `metadata` of openvidu-browser method `Session.connect`	A String with the participant client-side metadata (generated when calling `Session.connect` method)
`serverData`	Metadata associated to this participant from the server side. This corresponds to parameter `data` of REST API operation POST /openvidu/api/sessions/<SESSION_ID>/connection or its Java/Node server SDKs variants	A String with the participant server-side metadata

participantLeft 🔗

Recorded when a user has left a session.

{
    "event": "participantLeft",
    "timestamp": 1601395365655,
    "sessionId": "ses_Jd8tUyvhXO",
    "startTime": 1601394715606,
    "duration": 650,
    "reason": "disconnect",
    "connectionId": "con_EIeO06zgMz",
    "location": "Berlin, Germany",
    "ip": "37.122.145.190",
    "platform": "Chrome 85.0.4183.121 on Linux 64-bit",
    "clientData": "Mike",
    "serverData": "{'user': 'client1'}"
}

Property	Description	Value
`event`	Event type	`participantLeft`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`sessionId`	Session for which the event was triggered	A String with the session's unique identifier
`connectionId`	Identifier of the participant	A String with the participant's unique identifier
`location`	Geo location of the participant PRO	A String with format `"CITY, COUNTRY"` (or `"unknown"`)
`ip`	The IP of the participant, as seen by OpenVidu Server	A String with the participant's IP
`platform`	Complete description of the platform used by the participant to connect to the session	A String with the platform description
`clientData`	Metadata associated to this participant from the client side. This corresponds to parameter `metadata` of openvidu-browser method `Session.connect`	A String with the participant client-side metadata (generated when calling `Session.connect` method)
`serverData`	Metadata associated to this participant from the server side. This corresponds to parameter `data` of REST API operation POST /openvidu/api/sessions/<SESSION_ID>/connection or its Java/Node server SDKs variants	A String with the participant server-side metadata
`startTime`	Time when the participant joined the session	A Number (UTC milliseconds)
`duration`	Total duration of the participant's connection to the session	A Number with the duration in seconds
`reason`	How the participant left the session (complete description)	A String with one of these possible values `"disconnect"` `"forceDisconnectByUser"` `"forceDisconnectByServer"` `"sessionClosedByServer"` `"networkDisconnect"` `"mediaServerDisconnect"` `"nodeCrashed"` `"openviduServerStopped"`

webrtcConnectionCreated 🔗

Recorded when a new media stream has been established. Can be an "INBOUND" connection (the user is receiving a stream from a publisher of the session) or an "OUTBOUND" connection (the user is a publishing a stream to the session).

{
    "event": "webrtcConnectionCreated",
    "timestamp": 1601394849759,
    "sessionId": "ses_Jd8tUyvhXO",
    "streamId": "str_CAM_GPdf_con_EIeO06zgMz",
    "connectionId": "con_ThN5Rgi8Y8",
    "connection": "INBOUND",
    "receivingFrom": "con_EIeO06zgMz",
    "videoSource": "CAMERA",
    "videoFramerate": 30,
    "videoDimensions": "{\"width\":1280,\"height\":720}",
    "audioEnabled": true,
    "videoEnabled": true
}

Property	Description	Value
`event`	Event type	`webrtcConnectionCreated`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`sessionId`	Session for which the event was triggered	A String with the session's unique identifier
`connectionId`	Identifier of the participant	A String with the participant's unique identifier
`connection`	Whether the media connection is an inbound connection (the participant is receiving media from OpenVidu) or an outbound connection (the participant is sending media to OpenVidu)	A String with one of these possible values `"INBOUND"` `"OUTBOUND"`
`receivingFrom`	If `connection` is `"INBOUND"`, the participant from whom the media stream is being received	A String with the participant (sender) unique identifier
`audioEnabled`	Whether the media connection has negotiated audio or not	A Boolean
`videoEnabled`	Whether the media connection has negotiated video or not	A Boolean
`videoSource`	If `videoEnabled` is `true`, the type of video that is being transmitted	A String with one of these possible values `"CAMERA"` `"SCREEN"` `"CUSTOM"` `"IPCAM"`
`videoFramerate`	If `videoEnabled` is `true`, the framerate of the transmitted video	A Number with the fps
`videoDimensions`	If `videoEnabled` is `true`, the dimensions transmitted video	A String with the dimensions (e.g. `"1920x1080"`)

webrtcConnectionDestroyed 🔗

Recorded when any media stream connection is closed.

{
    "event": "webrtcConnectionDestroyed",
    "timestamp": 1601394894238,
    "sessionId": "ses_Jd8tUyvhXO",
    "startTime": 1601394849759,
    "duration": 44,
    "reason": "unsubscribe",
    "streamId": "str_CAM_GPdf_con_EIeO06zgMz",
    "connectionId": "con_ThN5Rgi8Y8",
    "connection": "INBOUND",
    "receivingFrom": "con_EIeO06zgMz",
    "videoSource": "CAMERA",
    "videoFramerate": 30,
    "videoDimensions": "{\"width\":1280,\"height\":720}",
    "audioEnabled": true,
    "videoEnabled": true
}

Property	Description	Value
`event`	Event type	`webrtcConnectionDestroyed`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`sessionId`	Session for which the event was triggered	A String with the session's unique identifier
`connectionId`	Identifier of the participant	A String with the participant's unique identifier
`connection`	Whether the media connection is an inbound connection (the participant is receiving media from OpenVidu) or an outbound connection (the participant is sending media to OpenVidu)	A String with one of these possible values `"INBOUND"` `"OUTBOUND"`
`receivingFrom`	If `connection` is `"INBOUND"`, the participant from whom the media stream is being received	A String with the participant (sender) unique identifier
`audioEnabled`	Whether the media connection has negotiated audio or not	A Boolean
`videoEnabled`	Whether the media connection has negotiated video or not	A Boolean
`videoSource`	If `videoEnabled` is `true`, the type of video that is being transmitted	A String with one of these possible values `"CAMERA"` `"SCREEN"` `"CUSTOM"` `"IPCAM"`
`videoFramerate`	If `videoEnabled` is `true`, the framerate of the transmitted video	A Number with the fps
`videoDimensions`	If `videoEnabled` is `true`, the dimensions transmitted video	A String with the dimensions (e.g. `"1920x1080"`)
`startTime`	Time when the media connection was established	A Number (UTC milliseconds)
`duration`	Total duration of the media connection	A Number with the duration in seconds
`reason`	How the WebRTC connection was destroyed (complete description)	A String with one of these possible values `"unsubscribe"` `"unpublish"` `"disconnect"` `"forceUnpublishByUser"` `"forceUnpublishByServer"` `"forceDisconnectByUser"` `"forceDisconnectByServer"` `"sessionClosedByServer"` `"networkDisconnect"` `"mediaServerDisconnect"` `"mediaServerReconnect"` `"nodeCrashed"` `"openviduServerStopped"`

recordingStatusChanged 🔗

Recorded when the status of a recording has changed. The status may be:

started: the session is being recorded. This means the associated video(s) already exists and its size is greater than 0. NOTE: when using COMPOSED recording with video, this event does not mean there are publisher's streams being actually recorded in the video file. It only ensures the video file exists and its size is greater than 0.
stopped: the recording process has stopped and files are being processed. Depending on the type of OpenVidu deployment and configuration, properties duration and size can be set to 0 and url can be null. If this is the case, wait for status ready to get the final value of these properties.
ready: the recorded file has been successfully processed and is available for download. Properties duration, size and url will always be properly defined at this moment. For OpenVidu Pro deployments configured to upload recordings to S3 this status means that the recording has been successfully stored in the S3 bucket.
failed: the recording process has failed. The final state of the recorded file cannot be guaranteed to be stable.

{
    "event": "recordingStatusChanged",
    "timestamp": 1601395005555,
    "sessionId": "ses_Jd8tUyvhXO",
    "startTime": 1601394992838,
    "duration": 8.6,
    "reason": "recordingStoppedByServer",
    "id": "ses_Jd8tUyvhXO",
    "name": "MyRecording",
    "outputMode": "COMPOSED",
    "resolution": "1280x720",
    "recordingLayout": "BEST_FIT",
    "hasAudio": true,
    "hasVideo": true,
    "size": 1973428,
    "status": "ready"
}

Property	Description	Value
`event`	Event type	`recordingStatusChanged`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`sessionId`	Session for which the event was triggered	A String with the session's unique identifier
`startTime`	Time when the recording started	A Number (UTC milliseconds)
`id`	Unique identifier of the recording	A String with the recording unique identifier
`name`	Name given to the recording file	A String with the recording name
`outputMode`	Output mode of the recording (`COMPOSED` or `INDIVIDUAL`)	A String with the recording output mode
`hasAudio`	Whether the recording file has audio or not	A Boolean
`hasVideo`	Whether the recording file has video or not	A Boolean
`recordingLayout`	The type of layout used in the recording. Only defined if `outputMode` is `COMPOSED` and `hasVideo` is true	A String with the `RecordingLayout` value (`"BEST_FIT"`, `"PICTURE_IN_PICTURE"`, `"CUSTOM"` ... )
`resolution`	Resolution of the recorded file. Only defined if `outputMode` is `COMPOSED` and `hasVideo` is true	A String with the width and height of the video file in pixels. e.g. `"1280x720"`
`size`	The size of the video file. Only guaranteed to be greater than `0` if status is `ready`	A Number with the size in bytes
`duration`	Duration of the video file. Only guaranteed to be greater than `0` if status is `ready`	A Number with the duration in seconds
`status`	Status of the recording	A String with one of these possible values `"started"` `"stopped"` `"ready"` `"failed"`
`reason`	Why the recording stopped. Only defined when status is stopped or ready (complete description)	A String with one of these possible values `"recordingStoppedByServer"` `"lastParticipantLeft"` `"sessionClosedByServer"` `"mediaServerDisconnect"` `"mediaServerReconnect"` `"nodeCrashed"` `"openviduServerStopped"` `"automaticStop"`

filterEventDispatched 🔗

Recorded when a filter event has been dispatched. This event can only be triggered if a filter has been applied to a stream and a listener has been added to a specific event offered by the filter. See Voice and video filters to learn more.

{
    "event": "filterEventDispatched",
    "timestamp": 1601394994829,
    "sessionId": "ses_Jd8tUyvhXO",
    "connectionId": "con_EIeO06zgMz",
    "streamId": "str_CAM_GPdf_con_EIeO06zgMz",
    "filterType": "ZBarFilter",
    "eventType": "CodeFound",
    "data": "{timestampMillis=1568645808285, codeType=EAN-13, source=23353-1d3c_kurento.MediaPipeline/1f56f4a5-807c-71a30d40_kurento.ZBarFilter, type=CodeFound, value=0012345678905, tags=[], timestamp=1568645808}"
}

Property	Description	Value
`event`	Event type	`filterEventDispatched`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`sessionId`	Session for which the event was triggered	A String with the session's unique identifier
`connectionId`	Identifier of the participant	A String with the participant's unique identifier
`streamId`	Identifier of the stream for which the filter is applied	A String with the stream unique identifier
`filterType`	Type of the filter applied to the stream	A String with the type of filter
`eventType`	Event of the filter that was triggered	A String with the type of event
`data`	Data of the filter event	A String with the data returned by the filter event. Its value will depend on the type of filter and event

signalSent 🔗

Recorded when a signal has been sent to a Session. Signals can be sent:

By the clients with openvidu-browser method Session.signal
By the application's server with REST API method POST /openvidu/api/signal

All kind of signals trigger signalSent event.

{
    "event": "signalSent",
    "timestamp": 1605181948719,
    "sessionId": "ses_Jd8tUyvhXO",
    "from": "con_ZbNTYgi0ae",
    "to": ["con_Yz3To5z53q"],
    "type": "my-chat",
    "data": "{'message':'Hello!','name':'Alice'}"
}

Property	Description	Value
`event`	Event type	`signalSent`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`sessionId`	Session for which the event was triggered	A String with the session's unique identifier
`from`	Identifier of the participant that sent the signal, or `null` if sent by the application's server	A String with the participant's unique identifier, or `null`
`to`	Array of participant identifiers to whom the message was addressed	An Array of Strings
`type`	Type of the signal	A String
`data`	Actual data of the signal	A String

nodeCrashed 🔗

This event is part of OpenVidu PRO and ENTERPRISE editions.

Recorded when a node of an OpenVidu Pro/Enterprise cluster has crashed. This is related to the the fault tolerance capabilities of OpenVidu:

It can be a Media Node for OpenVidu Pro and OpenVidu Enterprise clusters.
It can also be a Master Node for OpenVidu Enterprise HA clusters.

When a node crashes, all of its sessions are automatically closed and the node is removed from the OpenVidu cluster. No session is automatically reconstructed: it is the responsibility of the application to rebuild any affected session. Check out the following points for further information:

This event is always followed by other events for any session that was being hosted by the crashed node. All of them with reason property set to nodeCrashed: webrtcConnectionDestroyed, participantLeft, sessionDestroyed, recordingStatusChanged. Finally events mediaNodeStatusChanged will be triggered (first to status terminating and secondly to statusterminated), informing that the crashed Media Node is no longer part of the cluster.

Check out Media Node reconnection configuration for further information on this event, when triggered for Media Nodes.

{
    "event": "nodeCrashed",
    "timestamp": 1622548109518,
    "id": "media_i-1234567890abcdef0",
    "environmentId": "i-1234567890abcdef0",
    "ip": "172.17.0.3",
    "uri": "ws://172.17.0.3:8888/kurento",
    "nodeRole": "medianode",
    "sessionIds": ["ses_Jd8tUyvhXO","ses_6rttUnoF2w"],
    "recordingIds": ["ses_Jd8tUyvhXO"],
    "broadcasts": ["ses_6rttUnoF2w"],
    "clusterId": "MY_CLUSTER"
}

Property	Description	Value
`event`	Event type	`nodeCrashed`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`id`	Unique identifier of the crashed node	A String with the node's unique identifier
`environmentId`	Unique identifier of the crashed node, dependent on the deployment environment. For example, an AWS EC2 machine id if the cluster is deployed in AWS	A String with the node's environment unique identifier
`ip`	IP of the crashed node	A String with the node's IP
`uri`	URI of the crashed node	A String with the node's URI
`clusterId`	OpenVidu Pro cluster identifier. This allows you to identify the specific cluster to which the node triggering this event belongs, especially if you have more than one OpenVidu Pro cluster running (see )	A String with the cluster identifier
`nodeRole`	Role of the crashed node	A String with the node's role. It can be: `medianode` : if a Media Node has crashed. See OpenVidu Pro Fault Tolerance `masternode` : if a Master Node has crashed. See Fault tolerance in OpenVidu Enterprise HA
`sessionIds`	The collection of session identifiers of all the sessions that were located in the crashed node. This way you can immediately know which sessions have been destroyed by the crash	An Array of Strings
`recordingIds`	The collection of recording identifiers of all the recordings that were located in the crashed node. This way you can immediately know which recordings have been affected by the crash	An Array of Strings
`broadcasts`	The collection of session identifiers of all the sessions that were being broadcasted and which broadcast was located in the crashed node. This way you can immediately know which broadcasts have been affected by the crash. See Broadcast to YouTube/Twitch	An Array of Strings
`timeOfDisconnection`	Time when the connection with the Media Node was lost. It will be smaller than `timestamp`: the difference between both values is the time OpenVidu tried to reconnect to it	A Number (UTC milliseconds)

nodeRecovered 🔗

This event is part of OpenVidu PRO and ENTERPRISE editions.

Recorded when a Media Node of an OpenVidu Pro/Enterprise cluster has been reconnected after a crash.

Event nodeRecovered event only takes place for a Media Node if two conditions are met:

A nodeCrashed event has been previously triggered for the Media Node.
Configuration property OPENVIDU_PRO_CLUSTER_RECONNECTION_TIMEOUT grants sufficient time for the event nodeRecovered to be triggered before event mediaNodeStatusChanged with status terminating is produced (and therefore the Media Node is removed from the cluster).

Check out Media Node reconnection configuration for further information on this event.

{
    "event": "nodeRecovered",
    "timestamp": 1622548120514,
    "id": "media_i-1234567890abcdef0",
    "environmentId": "i-1234567890abcdef0",
    "ip": "172.17.0.3",
    "uri": "ws://172.17.0.3:8888/kurento",
    "nodeRole": "medianode",
    "clusterId": "MY_CLUSTER"
}

Property	Description	Value
`event`	Event type	`nodeRecovered`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`id`	Unique identifier of the recovered node	A String with the node's unique identifier
`environmentId`	Unique identifier of the recovered node, dependent on the deployment environment. For example, an AWS EC2 machine id if the cluster is deployed in AWS	A String with the node's environment unique identifier
`ip`	IP of the recovered node	A String with the node's IP
`uri`	URI of the recovered node	A String with the node's URI
`clusterId`	OpenVidu Pro cluster identifier. This allows you to identify the specific cluster to which the node triggering this event belongs, especially if you have more than one OpenVidu Pro cluster running (see )	A String with the cluster identifier
`nodeRole`	Role of the recovered node	`medianode`

mediaNodeStatusChanged 🔗

This event is part of OpenVidu PRO and ENTERPRISE editions.

Recorded when the status of a Media Node of an OpenVidu Pro cluster has changed. Below you have the finite-state machine defining the lifecycle of a Media Node and all of the possible transitions between its statuses. Visit Scalability section for a full description of them.

{
    "event": "mediaNodeStatusChanged",
    "timestamp": 1583750581667,
    "id": "media_i-1234567890abcdef0",
    "environmentId": "i-1234567890abcdef0",
    "ip": "172.17.0.3",
    "uri": "ws://172.17.0.3:8888/kurento",
    "newStatus": "running",
    "oldStatus": "launching",
    "clusterId": "MY_CLUSTER"
}

Property	Description	Value
`event`	Event type	`mediaNodeStatusChanged`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`id`	Unique identifier of the Media Node	A String with the Media Node unique identifier
`environmentId`	Unique identifier of the Media Node, dependent on the deployment environment. For example, an AWS EC2 machine id if the cluster is deployed in AWS	A String with the Media Node environment unique identifier
`ip`	IP of the Media Node	A String with the Media Node IP
`uri`	URI of the Media Node. This is the actual direction where OpenVidu Server Pro Media Node connects to this Media Node	A String with the Media Node URI
`clusterId`	OpenVidu Pro cluster identifier. This allows you to identify the specific cluster to which the Media Node triggering this event belongs, especially if you have more than one OpenVidu Pro cluster running (see )	A String with the cluster identifier
`oldStatus`	Old status of the Media Node. See Media Node statuses	A String with the Media Node old status. `null` if newStatus is `launching`
`newStatus`	New status of the Media Node. See Media Node statuses	A String with the Media Node new status

autoscaling 🔗

This event is part of OpenVidu PRO and ENTERPRISE editions.

Recorded when autoscaling is enabled and the autoscaling algorithm has generated any kind of change in the status of the Media Nodes. This includes Media Nodes that must be launched and Media Nodes that must be terminated, taking into account the different statuses the Media Nodes may have in order to make the most optimal decision. That is: which specific Media Nodes must transit from which previous status to which new status in order to reach the new desired number of Media Nodes in the least possible amount of time.

For example, when a new Media Node is needed, the algorithm will always prioritize transitioning Media Nodes in waiting-idle-to-terminate status to running status, instead of launching a brand new Media Node. And if some Media Node must be removed because the load is low enough, the algorithm will always cancel any launching Media Node (setting its status to canceled) instead of removing a running one. Check out Media Node statuses and austocaling sections to learn more.

An autoscaling event will always be followed by one or more mediaNodeStatusChanged events applying the required changes to the cluster.

{
    "event": "autoscaling",
    "timestamp": 1592994854492,
    "clusterId": "MY_CLUSTER",
    "reason": "The cluster average load (7.95%) is below its limits [30.00%, 70.00%] and the lower limit of Media Nodes (1) has not been reached. Current number of active nodes is 3 (2 launching and 1 running). 2 launching Media Nodes will be canceled.",
    "mediaNodes": {
        "launch": {
        "total": 0,
        "newNodes": 0,
        "waitingIdleToTerminateNodes": [],
        "canceledNodes": []
        },
        "terminate": {
        "total": 2,
        "runningNodes": [],
        "launchingNodes": [
            {
            "id": "media_i-1234567890abcdef0",
            "environmentId": null,
            "ip": null,
            "load": 0,
            "status": "launching"
            },
            {
            "id": "media_i-jfwojap393k2p332p",
            "environmentId": null,
            "ip": null,
            "load": 0,
            "status": "launching"
            }
        ]
        }
    },
    "system": {
        "config": {
        "maxNodes": 3,
        "minNodes": 1,
        "maxAvgLoad": 70,
        "minAvgLoad": 30
        },
        "status": {
        "numNodes": 3,
        "totalLoad": 23.84,
        "avgLoad": 7.946666666666666,
        "runningNodes": [
            {
            "id": "media_i-1234567890abcdef0",
            "environmentId": "i-1234567890abcdef0",
            "ip": "172.17.0.2",
            "load": 23.84,
            "status": "running"
            }
        ],
        "launchingNodes": [
            {
            "id": "media_i-jfwojap393k2p332p",
            "environmentId": "i-jfwojap393k2p332p",
            "ip": null,
            "load": 0,
            "status": "launching"
            },
            {
            "id": "media_i-po39jr3e10rkjsdfj",
            "environmentId": "i-po39jr3e10rkjsdfj",
            "ip": null,
            "load": 0,
            "status": "launching"
            }
        ],
        "waitingIdleToTerminateNodes": [],
        "canceledNodes": []
        }
    }
}

Property	Description	Value
`event`	Event type	`autoscaling`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`clusterId`	Unique identifier of this OpenVidu Pro cluster (configuration property `OPENVIDU_PRO_CLUSTER_ID`)	A String with the OpenVidu Pro cluster unique identifier
`reason`	A detailed description of why the autoscaling algorithm triggered this adjustment on the cluster size	A String with the reason of the autoscaling event
`mediaNodes`	An Object with the Media Nodes affected by the autoscaling event	An Object. See mediaNodes
`system`	An Object with a complete description of the system regarding the state of autoscaling	An Object. See system

mediaNodes 🔗

Property	Description	Value
`launch`	Media Nodes that are going to be added to the cluster	An Object with 4 properties: `total` : a Number counting the total amount of Media Nodes that are going to be added to the cluster (sum of the following properties). `newNodes` : a Number counting the amount of completely new Media Nodes that will be launched. For On Premises OpenVidu Pro clusters, this is the number of Media Nodes that must be manually launched and/or added to the cluster. `waitingIdleToTerminateNodes` : an Array of Objects of type mediaNode, that are transitioning from `waiting-idle-to-terminate` status to `running` status. `canceledNodes` : an Array of Objects of type mediaNode, that are transitioning from `canceled` status to `launching` status.
`terminate`	Media Nodes that are going to be removed from the cluster	An Object with 3 properties: `total` : a Number counting the total amount of Media Nodes that are going to be removed from the cluster (sum of the following properties). `runningNodes` : an Array of Objects of type mediaNode, that are transitioning from `running` status to A) `waiting-idle-to-terminate` status, if there are ongoing sessions inside the Media Node, or B) `terminating` status, if the Media Node is empty and can be immediately removed. `launchingNodes` : an Array of Objects of type mediaNode, that are transitioning from `launching` status to `canceled` status.

mediaNode 🔗

Property	Description	Value
`id`	Unique identifier of the Media Node	A String with the Media Node unique identifier
`environmentId`	Unique identifier of the Media Node, dependent on the deployment environment. For example, an AWS EC2 machine id if the cluster is deployed in AWS	A String with the Media Node environment unique identifier
`ip`	IP of the Media Node	A String with the Media Node IP
`load`	The CPU load of the Media Node	A Number. It is a decimal between 0.00 and 100.00
`status`	Status of the Media Node. See Media Node statuses	A String with the Media Node new status

system 🔗

Property	Description	Value
`config`	Autoscaling configuration	An Object with 4 properties with the current autoscaling-related configuration properties: `maxNodes` : a Number with the value of configuration property `OPENVIDU_PRO_CLUSTER_AUTOSCALING_MAX_NODES` `minNodes` : a Number with the value of configuration property `OPENVIDU_PRO_CLUSTER_AUTOSCALING_MIN_NODES` `maxAvgLoad` : a Number with the value of configuration property `OPENVIDU_PRO_CLUSTER_AUTOSCALING_MAX_LOAD` `minAvgLoad` : a Number with the value of configuration property `OPENVIDU_PRO_CLUSTER_AUTOSCALING_MIN_LOAD`
`status`	Current cluster status, including a complete description of its Media Nodes and the current load of the cluster	An Object. See status

status 🔗

Property	Description	Value
`numNodes`	Total number of active Media Nodes in the cluster. Active nodes are those in `running` or `launching` status	A Number
`totalLoad`	Total CPU load of the cluster. It is calculated with the sum of all Media Nodes that may have load greater than 0: those in `running` or `waiting-idle-to-terminate` status	A Number. It is a decimal between 0.00 and 100.00
`avgLoad`	The average load per Media Node. It is calculated by dividing `totalLoad` by `numNodes`. This parameter is the one compared to the limits set with configuration properties `OPENVIDU_PRO_CLUSTER_AUTOSCALING_MAX_LOAD` and `OPENVIDU_PRO_CLUSTER_AUTOSCALING_MIN_LOAD` to determine if the the cluster size must be modified	A Number. It is a decimal between 0.00 and 100.00
`runningNodes`	Media Nodes in `running` status	An Array of Objects of type mediaNode
`launchingNodes`	Media Nodes in `launching` status	An Array of Objects of type mediaNode
`waitingIdleToTerminateNodes`	Media Nodes in `waiting-idle-to-terminate` status	An Array of Objects of type mediaNode
`canceledNodes`	Media Nodes in `canceled` status	An Array of Objects of type mediaNode

HANodeRegistered 🔗

This event is part of OpenVidu ENTERPRISE HA On premises only. (Not available in OpenVidu Pro or Enterprise HA in AWS)

When a node is registered in an OpenVidu HA On premises cluster, this event is dispatched to the webhook endpoint. It contains the following information:

{
  "timestamp": 1687190118593,
  "event": "HANodeRegistered",
  "nodeId": "master_10.5.0.6",
  "ip": "10.5.0.6"
}

Property	Description	Value
`event`	Event type	`HANodeRegistered`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`nodeId`	Id of the node registered	A String with the node id
`ip`	IP of the node registered	A String with the node IP

HANodeDeregistered 🔗

This event is part of OpenVidu ENTERPRISE HA On premises only. (Not available in OpenVidu Pro or Enterprise HA in AWS)

When a node is deregistered in an OpenVidu HA On premises cluster, this event is dispatched to the webhook endpoint. It contains the following information:

{
  "timestamp": 1687281184225,
  "event": "HANodeDeregistered",
  "nodeId": "master_10.5.0.6",
  "ip": "10.5.0.6",
  "reason": "mediaNodeStatusTerminated"
}

Property	Description	Value
`event`	Event type	`HANodeDeregistered`
`timestamp`	Time when the event was triggered	A Number (UTC milliseconds)
`nodeId`	Id of the node registered	A String with the node id
`ip`	IP of the node registered	A String with the node IP
`reason`	Reason why the node was deregistered	A String with the reason. It could be `mediaNodeStatusTerminated` or `nodeCrashed`

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search