Webhook Integration - mekya/antmedia-doc GitHub Wiki

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.

Register Your Webhook URL

You can add default webhook URL to your streaming app on Ant Media Server. In addition, it lets you add custom specific webhook URL's in creating broadcast.

Add default Webhook URL

In order to add default URL, just follow the steps below

Open your apps red5-web.properties and add settings.listenerHookURL property to that file. red5-web.properties file is under webapps/<app_name>/WEB-INF folder
```
...
settings.listenerHookURL=http://www.example.com/webhook/
...
```

Open your apps red5-web.xml file and add settings.listenerHookURL to the app.settings bean.

...
<bean id="app.settings" class="io.antmedia.AppSettings">
...
  <property name="listenerHookURL" value="${settings.listenerHookURL}" />
...
</bean>
...

Restart the server on command line
```
sudo service antmedia restart
```

Right now, there is a default webhook URL for your app.

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 rest service. createBroadcast method has Broadcast object parameter which has listenerHookURL field .

As a result, you can set listenerHookURL for creating stream at Ant Media Server.

Here is a sample JSON for using createBroadcast method with Postman

{
	"variables": [],
	"info": {
		"name": "samples",
		"_postman_id": "cbef37ab-d4ae-c349-4845-b4a91d1ab201",
		"description": "",
		"schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
	},
	"item": [
		{
			"name": "http://localhost:5080/LiveApp/rest/broadcast/create",
			"request": {
				"url": "http://localhost:5080/LiveApp/rest/broadcast/create",
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"value": "application/json",
						"description": ""
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\"name\":\"test_video\", \"listenerHookURL\":\"http://www.example.com/webhook\"}"
				},
				"description": "ListenerHookURL sample"
			},
			"response": []
		}
	]
}

Webhooks List

It's time to know when Ant Media Server calls webhooks with which parameters. Here is a simple list for that

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

That's all. As a result, you can take some custom actions according to your project by checking action variable in your backend URL.

We hope this post will help you to make automation in your project. Please keep in touch if you have any question. We will be happy if we can help you.

Attention: Please process the result in your backend URL as soon as possible because these callbacks is called in event loop threads that does not support long running operations.