diff --git a/docs/guides/advanced-usage/webhooks.md b/docs/guides/advanced-usage/webhooks.md index ecf46303..409dbbd3 100644 --- a/docs/guides/advanced-usage/webhooks.md +++ b/docs/guides/advanced-usage/webhooks.md @@ -7,7 +7,7 @@ sidebar_position: 3 # Using webhooks -Ant Media Server provides webhooks for making your system/app know when certain events occurs on the server. Therefore, you can register your URL to Ant Media Server which makes POST request when a live stream is started, finished or recorded. Firstly,  let's look at how to register your backend URL to Ant Media Server as a webhook. After that, we'll provide reference for webhooks. +Ant Media Server provides webhooks for making your system/app know when certain events occurs on the server. Therefore, you can register your URL to Ant Media Server which makes POST request when a live stream is started, finished or recorded. Firstly, let's look at how to register your backend URL to Ant Media Server as a webhook. After that, we'll provide reference for webhooks. ![](@site/static/img/68747470733a2f2f616e746d656469612e696f2f77702d636f6e74656e742f75706c6f6164732f323031382f31312f776562686f6f6b732d333030783237332e706e67.png) ### Register Your Webhook URL @@ -23,9 +23,9 @@ Your Ant Media Server now has a default hook which is called when certain events #### Add Custom Webhook for Streams -Ant Media Server provides creating streams through rest service. Therefore, If you want to specify the webhook URL for each stream, you can use _createBroadcast_ method in the [rest service.](https://github.com/ant-media/Ant-Media-Server/blob/master/src/main/java/io/antmedia/rest/BroadcastRestService.java)  _createBroadcast_ method has Broadcast object parameter which has _listenerHookURL_ field_._ +Ant Media Server provides creating streams through rest service. Therefore, If you want to specify the webhook URL for each stream, you can use _createBroadcast_ method in the [rest service.](https://github.com/ant-media/Ant-Media-Server/blob/master/src/main/java/io/antmedia/rest/BroadcastRestService.java) _createBroadcast_ method has Broadcast object parameter which has _listenerHookURL_ field_._ -As a result,  you can set _listenerHookURL_ for creating a stream at Ant Media Server. +As a result, you can set _listenerHookURL_ for creating a stream at Ant Media Server. Here is a sample JSON for using _createBroadcast_ method with [Postman](https://www.getpostman.com/) ``` @@ -77,40 +77,42 @@ Ant Media Server supports webhook reliability starting from version 2.8.3. When Ant Media Server will hook to your website using a POST request with "application/x-www-form-urlencoded" as the body. Some example responses are: -* **liveStreamStarted:** Ant Media server calls this hook when a new live stream is started. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables - * **id**:  stream id of the broadcast +* **liveStreamStarted:** Ant Media server calls this hook when a new live stream is started. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables + * **id**: stream id of the broadcast * **action**: "liveStreamStarted" * **streamName**: stream name of the broadcast. It can be null. - * **category**:  stream category of the broadcast. It can be null. -* **liveStreamEnded:** Ant Media Server calls this hook when a live stream is ended. It sends **POST(application/x-www-form-urlencoded)**request to URL with following variables. - * **id:** stream id of the broadcast - * **action:** "liveStreamEnded" - * **streamName:** stream name of the broadcast. It can be null. - * **category:** stream category of the broadcast. It can be null. -* **vodReady:** Ant Media Server calls this hook when the recording of the live stream is ended. It sends **POST(application/x-www-form-urlencoded)**request to URL with following variables. - * **id**: stream id of the broadcast - * **action:** "vodReady" - * **vodName:**  vod file name - * **vodId:**  vod id in the datastore -* **endpointFailed:** Ant Media server calls this hook when the RTMP endpoint broadcast went into the failed status. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables - * **id**:  stream id of the broadcast + * **category**: stream category of the broadcast. It can be null. +* **liveStreamEnded:** Ant Media Server calls this hook when a live stream is ended. It sends **POST(application/x-www-form-urlencoded)**request to URL with following variables. + * **id:** stream id of the broadcast + * **action:** "liveStreamEnded" + * **streamName:** stream name of the broadcast. It can be null. + * **category:** stream category of the broadcast. It can be null. +* **vodReady:** Ant Media Server calls this hook when the recording of the live stream is ended. It sends **POST(application/x-www-form-urlencoded)**request to URL with following variables. + * **id**: stream id of the broadcast + * **action:** "vodReady" + * **vodName:** vod file name + * **vodId:** vod id in the datastore +* **endpointFailed:** Ant Media server calls this hook when the RTMP endpoint broadcast went into the failed status. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables + * **id**: stream id of the broadcast * **action**: "endpointFailed" * **streamName**: stream name of the broadcast. It can be null. - * **category**:  stream category of the broadcast. It can be null. - * **metadata**:  RTMP URL of the endpoint. -* **publishTimeoutError:** Ant Media server calls this hook when there is a publish time out error, it generally means that the server is not getting any frames. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables - * **id**:  stream id of the broadcast + * **category**: stream category of the broadcast. It can be null. + * **metadata**: RTMP URL of the endpoint. +* **publishTimeoutError:** Ant Media server calls this hook when there is a publish time out error, it generally means that the server is not getting any frames. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables + * **id**: stream id of the broadcast * **action**: "endpointFailed" * **streamName**: stream name of the broadcast. It can be null. - * **category**:  stream category of the broadcast. It can be null. -* **encoderNotOpenedError:** Ant Media server calls this hook when the encoder can't be opened. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables - * **id**:  stream id of the broadcast + * **category**: stream category of the broadcast. It can be null. +* **encoderNotOpenedError:** Ant Media server calls this hook when the encoder can't be opened. It sends **POST (application/x-www-form-urlencoded)**request to URL with following variables + * **id**: stream id of the broadcast * **action**: "encoderNotOpenedError" * **streamName**: stream name of the broadcast. It can be null. - * **category**:  stream category of the broadcast. It can be null. + * **category**: stream category of the broadcast. It can be null. That's all. As a result, you can now determine the type of the request by using the _action_ parameter within the POST request. -We hope this post will help you to make automation in your project.  Please [keep in touch](https://antmedia.io/#contact) if you have any question. We will be happy if we can help you. +We hope this post will help you to make automation in your project. Please [keep in touch](https://antmedia.io/#contact) if you have any question. We will be happy if we can help you. > **Attention:** Please process the POST request within your application as quick as possible as the hooks are called within the event loop thread which will not wait for your application to complete complex tasks. + +To secure streams using Webhook, refer to the [Webhook Authorization](https://antmedia.io/docs/category/stream-security/webhook-stream-authorization) document. diff --git a/docs/guides/stream-security/cors-filter.md b/docs/guides/stream-security/cors-filter.md index cf0a971c..740a0d4c 100644 --- a/docs/guides/stream-security/cors-filter.md +++ b/docs/guides/stream-security/cors-filter.md @@ -1,67 +1,104 @@ --- title: CORS Filter -description: This guide explains stream security options in Ant Media Server, and how you can Enable Disable, or Accept Undefined Streams. +description: This guide explains stream security options in Ant Media Server and how you can enable, disable, or accept undefined Streams. keywords: [Enable or Disable Undefined Streams, Accept Undefined Streams, One Time Token Control, Stream security, Ant Media Server Documentation, Ant Media Server Tutorials] sidebar_position: 7 --- -CORS(Cross-Origin Resource Sharing) Filter is enabled and accepts requests from everywhere by default. +The CORS (Cross-Origin Resource Sharing) filter is enabled and accepts requests from everywhere by default. -If you want to customize by yourself CORS Filters in Application, you can access in ```SERVER_FOLDER``` / ```webapps``` / ```{Application}``` / ```WEB-INF``` / web.xml +If you want to customize the CORS filter at the application level, you can access the ```/usr/local/antmedia/webapps/AppName/WEB-INF/web.xml``` file. ```xml - - CorsFilter - io.antmedia.filter.CorsHeaderFilter - - cors.allowed.origins - * - - - cors.allowed.methods - GET,POST,HEAD,OPTIONS,PUT,DELETE - + + CorsFilter + io.antmedia.filter.CorsHeaderFilter + + cors.allowed.origins + * + + + cors.allowed.methods + GET,POST,HEAD,OPTIONS,PUT,DELETE + - - - cors.allowed.headers + + --> + + cors.allowed.headers Accept, Origin, X-Requested-With, Access-Control-Request-Headers, Content-Type, Access-Control-Request-Method, Authorization - - true - - - CorsFilter - /* - + + true + + + CorsFilter + /* + ``` -If you want to customize by yourself CORS Filters in Root, you can access in ```SERVER_FOLDER``` / ```webapps``` / ```root``` / ```WEB-INF``` / web.xml +In case, when trying to play the stream via any other domain or integrating the player into any domain then the CORS error can be faced. In that scenario, allow the specific domain and uncomment the commented part as below. ```xml - - CorsFilter - io.antmedia.filter.CorsHeaderFilter - - cors.allowed.origins - * - - - cors.allowed.methods - GET,POST,HEAD,OPTIONS,PUT,DELETE - - - - CorsFilter - /* - + + CorsFilter + io.antmedia.filter.CorsHeaderFilter + + cors.allowed.origins + https://domain:port + + + cors.allowed.methods + GET,POST,HEAD,OPTIONS,PUT,DELETE + + + + + cors.support.credentials + true + + + cors.allowed.headers + Accept, Origin, X-Requested-With, Access-Control-Request-Headers, Content-Type, Access-Control-Request-Method, Authorization + + true + + + CorsFilter + /* + +``` + +If you want to customize the CORS filter in root folder then you can do that by edit `web.xml` file under `/usr/local/antmedia/webapps/root/WEB-INF` + +```xml + + CorsFilter + io.antmedia.filter.CorsHeaderFilter + + cors.allowed.origins + * + + + cors.allowed.methods + GET,POST,HEAD,OPTIONS,PUT,DELETE + + + cors.allowed.headers + Accept, Origin, X-Requested-With, Access-Control-Request-Headers, Content-Type, Access-Control-Request-Method, Authorization, ProxyAuthorization + + + + CorsFilter + /* + ``` :::info -Quick Learn: [Tomcat CORS Filter](https://tomcat.apache.org/tomcat-8.0-doc/api/index.html?org/apache/catalina/filters/CorsFilter.html) +To learn more about CORS filter, check out [Tomcat CORS Filter](https://tomcat.apache.org/tomcat-8.0-doc/api/index.html?org/apache/catalina/filters/CorsFilter.html) ::: diff --git a/docs/guides/stream-security/jwt-stream-security-filter.md b/docs/guides/stream-security/jwt-stream-security-filter.md index 5a6e155f..2904990c 100644 --- a/docs/guides/stream-security/jwt-stream-security-filter.md +++ b/docs/guides/stream-security/jwt-stream-security-filter.md @@ -13,7 +13,7 @@ Sending a token parameter with every publish request and play request is require ## Generate JWT Token -JWT Token can be generated in two ways. One way to generate is using the [JWT debugger](https://jwt.io/#debugger-io) and other way is to generate the token using the [JWT token Rest API](https://antmedia.io/rest/#/BroadcastRestService/getJwtTokenV2). +JWT Token can be generated in two ways. One way to generate is using the [JWT debugger](https://jwt.io/#debugger-io) and other way is to generate the token using the [JWT token Rest API](https://antmedia.io/rest/#/default/getJwtTokenV2). - To generate the token in both ways, ```streamId```, ```expireDate``` and ```type``` parameters are required. The service returns tokenId diff --git a/docs/guides/stream-security/one-time-token-control.md b/docs/guides/stream-security/one-time-token-control.md index 2e078931..d183c5ea 100644 --- a/docs/guides/stream-security/one-time-token-control.md +++ b/docs/guides/stream-security/one-time-token-control.md @@ -13,7 +13,7 @@ Sending a token parameter with every publish request and play request is require ## Generate One Time Token -The token can be generated with [one-time token](https://antmedia.io/rest/#/BroadcastRestService/getTokenV2) Rest API, gets ```streamId```, ```expireDate``` and ```type``` as query parameters. The service returns tokenId and other parameters as a response. +The token can be generated with [one-time token](https://antmedia.io/rest/#/default/getTokenV2) Rest API, gets ```streamId```, ```expireDate``` and ```type``` as query parameters. The service returns tokenId and other parameters as a response. It is important that the ```streamId``` and ```type``` parameters are properly defined because ```tokenId``` needs to match with both ```streamId``` and ```type```. diff --git a/docs/guides/stream-security/time-based-one-time-password.md b/docs/guides/stream-security/time-based-one-time-password.md index ad5e8ce9..95bf571e 100644 --- a/docs/guides/stream-security/time-based-one-time-password.md +++ b/docs/guides/stream-security/time-based-one-time-password.md @@ -1,5 +1,5 @@ --- -title: Time based One Time Password +title: Time Based One Time Password description: This guide explains stream security options in Ant Media Server, and how you can Enable Disable, or Accept Undefined Streams. keywords: [Enable or Disable Undefined Streams, Accept Undefined Streams, One Time Token Control, Stream security, Ant Media Server Documentation, Ant Media Server Tutorials] sidebar_position: 4 @@ -25,7 +25,7 @@ After enabling TOTP on the server, the following operations should be performed You can generate the TOTP token without first registering the subscriber, but if `Accept Undefined Streams` option in stream security is not allowed, only pre-registered subscribers with pre-registered streamId can publish and play streams. -The user can create a new subscriber (publisher or player) by using [Add Subscriber](https://antmedia.io/rest/#/BroadcastRestService/addSubscriber) Rest API method. You should assign a base 32Ssecret to each subscriber at the time of creation. A secret key should be a multiple of 8 characters, as stated in the above note. +The user can create a new subscriber (publisher or player) by using [Add Subscriber](https://antmedia.io/rest/#/default/addSubscriber) Rest API method. You should assign a base 32Ssecret to each subscriber at the time of creation. A secret key should be a multiple of 8 characters, as stated in the above note. - The sample API call to register a subscriber for publishing: @@ -42,21 +42,21 @@ curl -X POST -H "Accept: Application/json" -H "Content-Type: application/json" ' ### Other Subscriber APIs - Get the subscriber list using the [following - API](https://antmedia.io/rest/#/BroadcastRestService/listSubscriberV2): + API](https://antmedia.io/rest/#/default/listSubscriberV2): ```bash curl -X 'GET' 'http://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscriber-stats/list/0/10' -H 'accept: application/json' ``` - Delete the subscribers using the [following - API](https://antmedia.io/rest/#/BroadcastRestService/revokeSubscribers): + API](https://antmedia.io/rest/#/default/revokeSubscribers): ```bash curl -X 'DELETE' 'https://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers' -H 'accept: application/json' ``` - Get the subscriber statistics using the [following - API](https://antmedia.io/rest/#/BroadcastRestService/listSubscriberStatsV2): + API](https://antmedia.io/rest/#/default/listSubscriberStatsV2): ```bash curl -X 'GET' 'https://test.antmedia.io:5443/Sandbox/rest/v2/broadcasts/test/subscribers/list/0/10' -H 'accept: application/json' @@ -64,7 +64,7 @@ curl -X 'GET' 'https://test.antmedia.io:5443/Sandbox/rest/v2/broadcasts/test/sub ## TOTP Token Creation -TOTP token can be created using [this Rest API](https://antmedia.io/rest/#/BroadcastRestService/getTOTP). +TOTP token can be created using [this Rest API](https://antmedia.io/rest/#/default/getTOTP). By default, the TOTP generated for playback remains valid for 60 seconds after its generation. Consequently, users intending to utilize this token must send a play request to AMS within this 60-second timeframe. @@ -97,9 +97,11 @@ curl -X 'GET' 'http://IP-adddress-or-domain:5080/Application_Name/rest/v2/broadc The subscriber block feature allows blocking a specific user from engaging in publishing, playback, or both at any given moment. This implies that even if the user is actively publishing or playing the stream, their ability to publish or play will cease until the block is removed or expires. Block is valid for all publish and play types. The subscriber block feature can be used in version 2.7.0 and later. -Before proceeding further, you need to enable the below property in the application settings as well. +Before proceeding further, you need to enable the below property in the application advanced settings as well. - timeTokenSubscriberOnly=true +```js +timeTokenSubscriberOnly=true +``` Please save the settings after making any changes. @@ -120,7 +122,7 @@ webRTCAdaptor.publish("teststream", null, "lastpeony", "451222"); ##(The 2nd parameter, which is null here, represents the token(for example a JWT), not subscriberCode) ``` -After utilizing the TOTP token for publishing, you can block the subscriber from publishing using a block request. To prevent the user from publishing for 120 seconds, send a [subscriber block API request](https://antmedia.io/rest/#/BroadcastRestService/blockSubscriber) as below. +After utilizing the TOTP token for publishing, you can block the subscriber from publishing using a block request. To prevent the user from publishing for 120 seconds, send a [subscriber block API request](https://antmedia.io/rest/#/default/blockSubscriber) as below. ```bash curl -X 'PUT' 'http://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers/subscriberId/block/120/publish' -H 'accept: application/json' @@ -158,7 +160,7 @@ webRTCAdaptor.play("teststream", null, "lastpeony", "451222"); ##(The 2nd parameter, which is null here, represents the token(for example a JWT), not subscriberCode) ``` -After utilizing the TOTP token for playing, you can block the subscriber from playing using a block request. To prevent the user from playing for 120 seconds, send a [subscriber block API request](https://antmedia.io/rest/#/BroadcastRestService/blockSubscriber) as below. +After utilizing the TOTP token for playing, you can block the subscriber from playing using a block request. To prevent the user from playing for 120 seconds, send a [subscriber block API request](https://antmedia.io/rest/#/default/blockSubscriber) as below. ```bash curl -X 'PUT' 'http://IP-address-or-domain:5080/Application_Name/rest/v2/broadcasts/streamId/subscribers/subscriberId/block/120/play' -H 'accept: application/json' diff --git a/docs/guides/advanced-usage/webhook-stream-authorization.md b/docs/guides/stream-security/webhook-stream-authorization.md similarity index 99% rename from docs/guides/advanced-usage/webhook-stream-authorization.md rename to docs/guides/stream-security/webhook-stream-authorization.md index c8c72f98..794fe2cf 100644 --- a/docs/guides/advanced-usage/webhook-stream-authorization.md +++ b/docs/guides/stream-security/webhook-stream-authorization.md @@ -2,7 +2,7 @@ title: Webhook Authorization description: Webhook Authorization keywords: [Webhook authentication, Webhook authorization, Stream Security, Ant Media Server Documentation, Ant Media Server Tutorials, authentication, stream authentication, play authentication, play security, publish security, publish authentication] -sidebar_position: 4 +sidebar_position: 8 --- # Webhook Authorization