AdmissionWebhooks (beta)
Overview
AdmissionWebhooks are HTTP callbacks that query the control server to control publishing and playback admission requests.
Users can use the AdmissionWebhook for a variety of purposes, including customer authentication, tracking published streams, hide app/stream names, logging and more.
Configuration
AdmissionWebhooks can be set up on VirtualHost, as shown below.
Key | Description |
ControlServerUrl | The HTTP Server to receive the query. HTTP and HTTPS are available. |
SecretKey | The secret key used when encrypting with HMAC-SHA1 For more information, see Security. |
Timeout | Time to wait for a response after request (in milliseconds) |
Enables | Enable Providers and Publishers to use AdmissionWebhooks |
Request
Format
AdmissionWebhooks send HTTP/1.1 request message to the configured user's control server when an encoder requests publishing or a player requests playback. The request message format is as follows.
The message is sent by POST method and the payload is in application/json format. X-OME-Signature is a value obtained by encrypting payload with HMAC-SHA1 so that ControlServer can verify the validity of this message. For more information on X-OME-Signature, see the Security section.
Here is a detailed explanation of each element of Json payload:
Element | Sub-Element | Description |
client | Information of the client who requested the connection. | |
address | Client's IP address | |
port | Client's Port number | |
request | Information about the client's request | |
direction | incoming : A client requests to publish a stream outgoing : A client requests to play a stream | |
protocol | webrtc, srt, rtmp, hls, dash, lldash | |
url | url requested by the client | |
time | time requested by the client (ISO8601 format) |
Security
The control server may need to validate incoming http requests for security reasons. For this, the AdmissionWebhooks module puts the X-OME-Signature
value in the HTTP request header. X-OME-Signature
is a value obtained by encrypting the payload of HTTP request with HMAC-SHA1 algorithm using the secret key set in <AdmissionWebhooks><SecretKey> of the configuration.
Conditions that triggers the request
As shown below, the trigger condition of request is different for each protocol.
Protocol | Condition |
WebRTC | When a client requests Offer SDP |
RTMP | When a client sends a publish message |
SRT | When a client send a streamid |
HLS | Every time a client requests a playlist |
DASH | Every time a client requests a playlist |
LL-DASH | Every time a client requests a playlist |
Response
Format
ControlServer must respond with the following Json format. In particular, the "allowed"
element is required.
Element | Description |
allowed (required) | true or false Allows or rejects the client's request. |
new_url (optional) | Redirects the client to a new url. However, the |
lifetime (optional) | The amount of time (in milliseconds) that a client can maintain a connection (Publishing or Playback)
HTTP based streaming (HLS, DASH, LLDASH) does not keep a connection, so this value does not apply. |
reason (optional) | If allowed is false, it will be output to the log. |
User authentication and control
new_url
redirects the original request to another app/stream. This can be used to hide the actual app/stream name from the user or to authenticate the user by inserting additional information instead of the app/stream name.
For example, you can issue a WebRTC streaming URL by inserting the user ID as follows: ws://domain.com:3333/user_id
It will be more effective if you issue a URl with the encrypted value that contains the user ID, url expiration time, and other information.
After the Control Server checks whether the user is authorized to play using user_id
, and responds with ws://domain.com:3333/app/sport-3
to new_url
, the user can play app/sport-3.
If the user has only one hour of playback rights, the Control Server responds by putting 3600000 in the lifetime
.
Last updated