AdmissionWebhooks (beta)
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.
AdmissionWebhooks can be set up on VirtualHost, as shown below.
<VirtualHost>
<AdmissionWebhooks>
<ControlServerUrl>https://192.168.0.161:9595/v1/admission</ControlServerUrl>
<SecretKey>1234</SecretKey>
<Timeout>3000</Timeout>
<Enables>
<Providers>rtmp,webrtc,srt</Providers>
<Publishers>webrtc,llhls</Publishers>
</Enables>
</AdmissionWebhooks>
</VirtualHost>
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 |
Timeout | Time to wait for a response after request (in milliseconds) |
Enables | Enable Providers and Publishers to use AdmissionWebhooks |
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.
POST /configured/tartget/url/ HTTP/1.1
Content-Length: 325
Content-Type: application/json
Accept: application/json
X-OME-Signature: f871jd991jj1929jsjd91pqa0amm1
{
"client":
{
"address": "211.233.58.86",
"port": 29291
},
"request":
{
"direction": "incoming | outgoing",
"protocol": "webrtc | rtmp | srt | llhls",
"status": "opening | closing",
"url": "scheme://host[:port]/app/stream/file?query=value&query2=value2",
"time": ""2021-05-12T13:45:00.000Z"
}
}
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:
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 |
| status | opening : A client requests to open a stream outgoing : A client closed the stream |
| url | url requested by the client |
| time | time requested by the client (ISO8601 format) |
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.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 | |
LLHLS | When a client requests a playlist (llhls.m3u8) |
The engine in the closing state does not need any parameter in response. To the query just answer with empty json object.
HTTP/1.1 200 OK
Content-Length: 5
Content-Type: application/json
Connection: Closed
{
}
ControlServer must respond with the following Json format. In particular, the
"allowed"
element is required.HTTP/1.1 200 OK
Content-Length: 102
Content-Type: application/json
Connection: Closed
{
"allowed": true,
"new_url": "scheme://host[:port]/app/stream/file?query=value&query2=value2",
"lifetime": milliseconds,
"reason": "authorized"
}
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 scheme , port , and file cannot be different from the request. The host can only be changed to another virtual host on the same server. |
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. |
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 modified 7d ago