Webhook

Introduction

Webhook is an HTTP(S) endpoint used for pushing the notifications to your application. Event-based webhooks/user-defined HTTP webhooks, can be used to track the events in your room and build business logic, allowing you to create analytics on your traffic. Create an attendance system, for instance. Every session, 100ms sends a list of events to the URL you specify in the webhook configuration. For analytics and/or debugging, you can store these data on your server.

To handle a webhook, you must create a listener to accept these HTTP requests from 100ms.

Requirements

• Webhook MUST implement POST HTTP method for receiving notifications. 100ms notifications are in JSON format so it should be handled accordingly.
• To handle webhooks in your app, your endpoint should:
  • Capture HTTP requests
  • Respond to the requests
• When 100ms sends the HTTP request callbacks to the webhook during an event, you should capture the request and respond with a 200 OK response. You can store the webhook data in your database for later processing.

  Note: 100ms automatically retries webhooks three times if your server does not return an HTTP 200 status code.

  • First at 1 second after the original attempt.
  • Second at 3 seconds after the first retry attempt.
  • Third at 10 seconds after the second retry attempt.

How to secure webhooks

Additionally, you can specify headers which will be passed transparently to your webhook endpoint. This can be used for securing or tracing the origin of the request.

How to configure Webhook

Webhook can be configured using Developer section of 100ms Dashboard

Events

Event is a JSON dictionary which has the following keys.

Event Attributes

Sample Event Payload

{
    "version": "2.0",
    "id": "6c75de35-b778-4fb0-88ae-114c28dc285f",
    "account_id": "60b8e13a6eb86d8101b57354",
    "timestamp": "2021-08-08T07:04:15Z",
    "type": "peer.join.success",
    "data": {
        "joined_at": "2021-08-08T07:04:15.001380432Z",
        "peer_id": "83b869e1-9a4b-4037-84b2-913cf76e4392",
        "role": "host",
        "room_id": "60b8e13a6eb86d8101b57354",
        "room_name": "test room",
        "session_id": "610f81ee870dde099a249948",
        "template_id": "66112497abcd52312556c4gg",
        "user_id": "user.001",
        "user_name": "test user"
    }
}
 

List of events

Here's the list of events available on the 100ms platform.

Session Events

session.open.success

This event will be sent when session opens successfully.

Attributes

Sample session.open.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "app_id": "************************",
    "timestamp": "2021-11-30T12:58:49Z",
    "type": "session.open.success",
    "data": {
        "room_id": "************************",
        "room_name": "**********",
        "session_id": "************************",
        "template_id": "************************",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

session.close.success

This event will be sent when session closes successfully.

Attributes

Sample session.close.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "app_id": "************************",
    "timestamp": "2021-11-30T12:58:49Z",
    "type": "session.close.success",
    "data": {
        "room_id": "************************",
        "room_name": "**********",
        "session_id": "************************",
        "template_id": "************************",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

Peer Events

peer.join.success

This event will be sent when any peer joins the room successfully

Attributes

Sample peer.join.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T12:58:49Z",
    "type": "peer.join.success",
    "data": {
        "joined_at": "2021-11-30T12:58:49.97291247Z",
        "peer_id": "********-****-****-****-***********",
        "role": "********",
        "room_id": "************************",
        "room_name": "**********",
        "session_id": "************************",
        "template_id": "************************",
        "user_id": "************************",
        "user_name": "********",
        "user_data": "",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

peer.leave.success

This event will be sent when peer leaves the room

Attributes

Peer Leave Reason

1. client request
2. peer kicked
3. websocket closed
4. ice connection state closed

Note:

1. In case of peer is kicked / room is ended
   • Client itself initiates a peer leave on receiving the signal. In these cases, reason will be client request
   • Also, server starts a timer for the same. If peer leave is not received from client before the timer ends, the server then kicks the peer itself. In such cases, reason will be peer kicked
2. All other reasons except client request and peer kicked denote that the peer has left unexpectedly.

Sample peer.leave.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T12:58:58Z",
    "type": "peer.leave.success",
    "data": {
        "duration": 40,
        "left_at": "2021-11-30T12:58:58.500451704Z",
        "peer_id": "********-****-****-****-***********",
        "role": "********",
        "room_id": "************************",
        "room_name": "**********",
        "session_id": "************************",
        "template_id": "************************",
        "user_id": "************************",
        "user_name": "********",
        "user_data": "",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

peer.join.failure

This event will be sent when a peer fails to join a room. This can occur when,

1. Server is overloaded and results in timeout

2. Network disconnection

Attributes

Peer join failure Reason

1. role not allowed
2. network disconnection
3. duplicate peer id

Sample peer.join.failure event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-25T09:10:35Z",
    "type": "peer.join.failure",
    "data": {
        "joined_at": "0001-01-01T00:00:00Z",
        "peer_id": "********-****-****-****-***********",
        "role": "********",
        "room_id": "************************",
        "room_name": "**********",
        "user_id": "************************",
        "template_id": "************************",
        "user_name": "********",
        "user_data": "",
        "error_message": "role not allowed"
    }
}
 

peer.leave.failure

This event will be sent when the peer leave fails. This can occur when,

1. peer.leave is called twice

2. peer.leave is called before peer.join or if peer.join has failed

3. peer.leave is called after peer is kicked out of room / room has ended

Attributes

Peer leave failure Reason

1. peer not joined

Sample peer.leave.failure event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T12:55:51Z",
    "type": "peer.leave.failure",
    "data": {
        "duration": 0,
        "left_at": "0001-01-01T00:00:00Z",
        "peer_id": "********-****-****-****-***********",
        "role": "********",
        "room_id": "************************",
        "room_name": "**********",
        "user_id": "************************",
        "template_id": "************************",
        "user_name": "********",
        "user_data": "",
        "error_message": "Peer not joined"
    }
}
 

Room Events

room.end.success

This event will be sent when room end is called and the it is successful

Attributes

Sample room.end.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-25T09:10:35Z",
    "type": "room.end.success",
    "data": {
        "joined_at": "0001-01-01T00:00:00Z",
        "peer_id": "********-****-****-****-***********",
        "role": "********",
        "room_id": "************************",
        "room_name": "**********",
        "session_id": "************************",
        "template_id": "************************",
        "user_id": "************************",
        "user_name": "********",
        "lock_room": false,
        "reason": "****************",
        "source": "peer",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

Role change Events

role.change.success

This event will be sent when peer changes role successfully.

Attributes

Sample role.change.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "app_id": "************************",
    "timestamp": "2021-11-30T12:58:49Z",
    "type": "role.change.success",
    "data": {
        "joined_at": "2021-11-30T12:58:49.97291247Z",
        "peer_id": "********-****-****-****-***********",
        "role": "********",
        "room_id": "************************",
        "room_name": "**********",
        "session_id": "************************",
        "template_id": "************************",
        "user_id": "************************",
        "user_name": "********",
        "user_data": "",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

SFU Recording Events

recording.success

This event will be sent when final composed recording is generated and uploaded to the destination

Attributes

Sample recording.success event

{
    "version": "1.0",
    "id": "********-****-****-****-***********",
    "app_id": "************************",
    "account_id": "************************",
    "timestamp": "2021-11-30T20:12:35Z",
    "type": "recording.success",
    "data": {
        "URL": "https://<file-access-url>?<signature>",
        "duration": 351,
        "location": "s3://<file-bucket-address>.mp4",
        "room_id": "************************",
        "room_name": "TestRoom1",
        "session_id": "************************",
        "template_id": "************************",
        "size": 13933649,
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

recording.failed

This event will be sent when failure occurs during final recording composition or upload to storage

Attributes

Sample recording.failed event

{
    "version": "1.0",
    "id": "********-****-****-****-***********",
    "app_id": "************************",
    "account_id": "************************",
    "timestamp": "2021-11-23T09:04:25Z",
    "type": "recording.failed",
    "data": {
        "error": "Upload Failure",
        "room_id": "************************",
        "room_name": "TestRoom1",
        "session_id": "************************",
        "template_id": "************************",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

RTMP Streaming & Browser Recording Events

beam.started.success

This event is sent when RTMP streaming and/or browser recording is successfully triggered

Attributes

Sample beam.started.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T12:58:46Z",
    "type": "beam.started.success",
    "data": {
        "beam_id": "************************",
        "job_id": "************************",
        "metadata_id": "********-****-****-****-***********",
        "metadata_timestamp": "2021-11-30T12:58:46.400759043Z",
        "peer_id": "********-****-****-****-***********",
        "room_id": "************************",
        "session_id": "************************",
        "template_id": "************************",
        "start_delay": 12,
        "state_name": "Started",
        "state_timestamp": "2021-11-30T12:58:46.385555859Z",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

beam.stopped.success

This event is sent when RTMP streaming and/or browser recording is successfully stopped

Attributes

Sample beam.stopped.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T12:59:57Z",
    "type": "beam.stopped.success",
    "data": {
        "beam_id": "************************",
        "job_id": "************************",
        "metadata_id": "********-****-****-****-***********",
        "metadata_timestamp": "2021-11-30T12:59:57.797972469Z",
        "peer_id": "********-****-****-****-***********",
        "room_id": "************************",
        "session_id": "************************",
        "template_id": "************************",
        "state_name": "Stopped",
        "state_timestamp": "2021-11-30T12:59:57.685503281Z",
        "duration": 56,
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

beam.recording.success

This event is sent when beam successfully records the room and uploads the video to storage

Attributes

Sample beam.recording.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T12:59:57Z",
    "type": "beam.recording.success",
    "data": {
        "beam_id": "************************",
        "created_at": "2021-11-30T12:59:57.672493658Z",
        "duration": 79,
        "location": "https://<file access URL>",
        "metadata_id": "********-****-****-****-***********",
        "metadata_timestamp": "2021-11-30T12:59:57.679491494Z",
        "peer_id": "********-****-****-****-***********",
        "room_id": "************************",
        "started_at": "2021-11-30T12:58:34.051Z",
        "stopped_at": "2021-11-30T12:59:56.778Z",
        "session_id": "************************",
        "template_id": "************************",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

beam.failure

This event will be sent when there are failures in RTMP streaming and/or browser recording. This can occur when,

1. Invalid RTMP URL

2. Browser failed to load the web-app

3. Incorrect storage (S3) credentials

4. Other unexpected errors

Attributes

Sample beam.failure event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T20:36:55Z",
    "type": "beam.failure",
    "data": {
        "beam_id": "************************",
        "error_code": 1,
        "error_message": "[tcp @ 0x55f6cc5f5780] Failed to resolve hostname rvs-isr: Name or service not known",
        "error_type": "BeamFailed",
        "job_id": "************************",
        "metadata_id": "********-****-****-****-***********",
        "metadata_timestamp": "2021-11-30T20:36:55.807155801Z",
        "peer_id": "********-****-****-****-***********",
        "room_id": "************************",
        "session_id": "************************",
        "template_id": "************************",
        "state_message": "[tcp @ 0x55f6cc5f5780] Failed to resolve hostname rvs-isr: Name or service not known",
        "state_name": "Failed",
        "state_timestamp": "2021-11-30T20:36:55.799192444Z",
        "meeting_url": "https://app.100ms.live/preview/rpe-pwl-akt?token=beam_recording",
        "rtmp": [{ "url": "http://test.com" }],
        "duration": 56,
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

HLS Streaming Events

hls.started.success

This event is sent when hls streaming is successfully triggered

Attributes

Sample hls.started.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T12:58:46Z",
    "type": "hls.started.success",
    "data": {
        "beam_id": "************************",
        "job_id": "************************",
        "metadata_id": "********-****-****-****-***********",
        "metadata_timestamp": "2021-11-30T12:58:46.400759043Z",
        "peer_id": "********-****-****-****-***********",
        "room_id": "************************",
        "meeting_url": "https://app.100ms.live/preview/rpe-pwl-akt?token=beam_recording",
        "session_id": "************************",
        "template_id": "************************",
        "start_delay": 12,
        "state_name": "HLSStarted",
        "state_timestamp": "2021-11-30T12:58:46.385555859Z",
        "url": "https://100ms-live.m3u8",
        "started_at": "2021-11-30T12:58:46.400759043Z",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

hls.stopped.success

This event is sent when hls streaming is successfully stopped

Attributes

Sample hls.stopped.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T12:59:57Z",
    "type": "hls.stopped.success",
    "data": {
        "beam_id": "************************",
        "job_id": "************************",
        "metadata_id": "********-****-****-****-***********",
        "metadata_timestamp": "2021-11-30T12:59:57.797972469Z",
        "peer_id": "********-****-****-****-***********",
        "room_id": "************************",
        "meeting_url": "https://app.100ms.live/preview/rpe-pwl-akt?token=beam_recording",
        "session_id": "************************",
        "template_id": "************************",
        "state_name": "HLSStopped",
        "state_timestamp": "2021-11-30T12:59:57.685503281Z",
        "duration": 56,
        "started_at": "2021-11-30T12:59:57.797972469Z",
        "stopped_at": "2021-11-30T12:59:57.797972469Z",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

hls.failure

This event will be sent when there are failures in RTMP streaming and/or browser recording. This can occur when,

1. Browser failed to load the web-app

2. Other unexpected errors

Attributes

Sample hls.failure event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T20:36:55Z",
    "type": "hls.failure",
    "data": {
        "beam_id": "************************",
        "error_code": 1,
        "error_message": "[tcp @ 0x55f6cc5f5780] Failed to resolve hostname rvs-isr: Name or service not known",
        "error_type": "BeamFailed",
        "job_id": "************************",
        "metadata_id": "********-****-****-****-***********",
        "metadata_timestamp": "2021-11-30T20:36:55.807155801Z",
        "peer_id": "********-****-****-****-***********",
        "room_id": "************************",
        "meeting_url": "https://app.100ms.live/preview/rpe-pwl-akt?token=beam_recording",
        "session_id": "************************",
        "template_id": "************************",
        "state_message": "[tcp @ 0x55f6cc5f5780] Failed to resolve hostname rvs-isr: Name or service not known",
        "state_name": "HLSFailed",
        "state_timestamp": "2021-11-30T20:36:55.799192444Z",
        "duration": 56,
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}
 

hls.recording.success

This event will be sent when hls recordings are successful and uploaded to the storage

Attributes

Sample hls.recording.success event

{
    "version": "2.0",
    "id": "********-****-****-****-***********",
    "account_id": "************************",
    "timestamp": "2021-11-30T20:36:55Z",
    "type": "hls.recording.success",
    "data": {
        "beam_id": "************************",
        "session_id": "************************",
        "template_id": "************************",
        "metadata_id": "********-****-****-****-***********",
        "metadata_timestamp": "2021-11-30T20:36:55.807155801Z",
        "peer_id": "********-****-****-****-***********",
        "room_id": "************************",
        "duration": 56,
        "meeting_url": "https://app.100ms.live/preview/rpe-pwl-akt?token=beam_recording",
        "recording_hls_vod_playlist_location": "https://<hls-vod-access-url>?<signature>",
        "recording_single_files": [
            {
                "layer": "0",
                "location": "s3://<file-0-bucket-address>.mp4",
                "presigned_url": "https://<file-0-access-url>?<signature-0>"
            },
            {
                "layer": "1",
                "location": "s3://<file-1-bucket-address>.mp4",
                "presigned_url": "https://<file-1-access-url>?<signature-1>"
            },
            {
                "layer": "2",
                "location": "s3://<file-2-bucket-address>.mp4",
                "presigned_url": "https://<file-2-access-url>?<signature-2>"
            },
            {
                "layer": "3",
                "location": "s3://<file-3-bucket-address>.mp4",
                "presigned_url": "https://<file-3-access-url>?<signature-3>"
            }
        ],
        "recording_thumbnails": [
            {
                "width": 1280,
                "height": 720,
                "offset": 60,
                "location": "s3://<thumbnail-file-bucket-address>.png",
                "url": "https://<thumbnail-access-url>?<signature3>"
            }
        ],
        "created_at": "2021-11-30T12:59:57.672493658Z",
        "started_at": "2021-11-30T12:59:57.797972469Z",
        "stopped_at": "2021-11-30T12:59:57.797972469Z",
        "session_started_at": "2021-11-30T12:58:49.97291247Z"
    }
}