AdmissionWebhooks
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.
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 in POST method and the payload is in application/json format. X-OME-Signature is a base64 url safe encoded value obtained by encrypting the payload with HMAC-SHA1 so that the ControlServer can validate this message. See the Security section for more information on X-OME-Signature.
Here is a detailed explanation of each element of Json payload:
OME searches for and sets the values in real_ip in the following order:
The value of the X-REAL-IP header
The value of the first item of X-FORWARDED-FOR
The IP of the client that is actually connected
Security
The control server may need to validate incoming http requests for security reasons. To do this, the AdmissionWebhooks module puts the X-OME-Signature
value in the HTTP request header. X-OME-Signature
is a base64 url safe encoded value obtained by encrypting the payload of an HTTP request with the 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.
Response for closing status
The engine in the closing state does not need any parameter in response. To the query just answer with empty json object.
Response for opening status
Format
ControlServer must respond with the following Json format. In particular, the "allowed"
element is required.
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
.