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.
<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
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.
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)
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.
Protocol
Condition
WebRTC
When a client requests Offer SDP
RTMP
When a client sends a publish message
SRT
When a client send a streamid​
LLHLS
When a client requests a playlist (llhls.m3u8)
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.
HTTP/1.1 200 OK
Content-Length: 5
Content-Type: application/json
Connection: Closed
{
}
Response for opening status
Format
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)
0 means infinity
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.

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

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)

Protocol	Condition
WebRTC	When a client requests Offer SDP
RTMP	When a client sends a publish message
SRT	When a client send a streamid
LLHLS	When a client requests a playlist (llhls.m3u8)

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) 0 means infinity 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.

SignedPolicy

Clustering

Last modified 7d ago