Webhook Integration in Ant Media Server: Complete Guide [2026]

Ant Media Server provides webhook support to notify external systems when specific streaming events occur. Webhooks allow your backend application to automatically receive event-based updates—such as when a live stream starts, ends, or a recording becomes available—without continuously polling the server.

By registering a webhook URL, Ant Media Server sends HTTP POST requests to your backend whenever a supported event is triggered. This enables developers to build automation workflows, trigger notifications, update databases, or integrate streaming events with other services in real time.

This comprehensive guide explains how to register webhook URLs in Ant Media Server, configure default and stream-specific webhooks, and understand the available webhook events and payloads for seamless integration.

Register Your Webhook URL

Ant Media Server allows you to configure a default webhook URL for a streaming application. This webhook will be triggered automatically for supported stream events such as stream start, stream end, and recording completion.

Add Default Webhook URL

To add a default webhook URL, follow these steps:

1. Open your app’s red5-web.properties file (located in webapps/<app_name>/WEB-INF) and add the settings.listenerHookURL property:
   

   settings.listenerHookURL=http://www.example.com/webhook/

   
   
2. For versions 1.6.0 and earlier, open red5-web.xml and add the property to the app.settings bean:
   

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

   
   
3. Restart the server:
   

   sudo service antmedia restart

   
   

Once the server restarts, the webhook URL is registered and will receive event notifications for the application.

Add Custom Webhook for Streams

Ant Media Server allows you to specify webhook URLs for individual streams using the createBroadcast method in the REST API. The createBroadcast method accepts a Broadcast object parameter with a listenerHookURL field.

Here is a sample JSON for using createBroadcast with Postman:

{
  "name": "test_stream",
  "listenerHookURL": "http://www.example.com/custom-webhook/"
}

Webhook Events

Ant Media Server sends webhook notifications as HTTP POST requests with content type application/x-www-form-urlencoded when specific streaming events occur. Each request includes an action parameter that identifies the event type.

Available Events

liveStreamStarted

Triggered when a new live stream starts. Includes the following parameters:

• id: Stream ID of the broadcast
• action: “liveStreamStarted”
• streamName: Stream name (can be null)
• category: Stream category (can be null)

liveStreamEnded

Triggered when a live stream ends. Includes the following parameters:

• id: Stream ID of the broadcast
• action: “liveStreamEnded”
• streamName: Stream name (can be null)
• category: Stream category (can be null)

vodReady

Triggered when recording of a live stream is completed. Includes the following parameters:

• id: Stream ID of the broadcast
• action: “vodReady”
• vodName: VOD file name

Frequently Asked Questions

What is the purpose of webhooks in Ant Media Server?

Webhooks in Ant Media Server allow external systems to receive real-time notifications when specific streaming events occur, such as when a live stream starts, ends, or when a recording is ready. This enables backend automation without the need for continuous polling.

What HTTP method and content type are used for webhook requests?

Ant Media Server sends webhook notifications as HTTP POST requests with the content type application/x-www-form-urlencoded. The request payload includes event-specific parameters such as the stream ID and action type.

Can I use different webhook URLs for different streams?

Yes, Ant Media Server supports per-stream webhook URLs. When creating a stream using the REST API, you can set a custom listenerHookURL for that stream. This custom webhook overrides the default application-level webhook URL.

What happens if my webhook endpoint is unavailable?

If the webhook endpoint is unreachable or returns a non-200 HTTP response, the event notification may fail to be delivered. It is recommended to ensure that the webhook endpoint is publicly accessible, reliable, and capable of handling POST requests from Ant Media Server.

Conclusion

Ant Media Server webhooks provide a simple and effective way to integrate streaming events with external systems. By using webhook notifications, applications can react in real time to stream lifecycle events without relying on polling or manual checks.

By configuring default or stream-specific webhook URLs, developers can build flexible automation workflows such as triggering notifications, updating databases, or integrating with third-party services. Understanding the available webhook events and their payloads ensures reliable and predictable integration.

When implementing webhooks, ensure your endpoint is publicly accessible, handles POST requests correctly, and responds with appropriate HTTP status codes to acknowledge event delivery.

For more information about Ant Media Server’s streaming capabilities, explore our documentation or contact our support team.