What is HTTP Notify?

HTTP Notify is a powerful feature that allows your Happytime Media Server to communicate with external business systems in real-time via HTTP callbacks (webhooks).

Whenever a significant event occurs (like a client connecting, starting to play or publish a stream), the server sends an HTTP POST request to your designated endpoint. Your application can then process this event and return a response to control whether the session proceeds.

This enables deep integration for:

• Authentication & Authorization: Verify user credentials before allowing a push or pull.
• Real-time Statistics: Log every connect, play, or publish event for analytics.
• Session Management: Track active streams and clients.
• Alerting & Monitoring: Trigger notifications when critical events happen.

Configuration Guide

To enable HTTP Notify, modify the media server configuration file by adding the <http_notify> section under the protocol-specific tags (<rtsp>, <rtmp>, etc.).

Full Configuration Example

Below is a complete example showing how to configure HTTP Notify for both RTSP and RTMP protocols:

<config>
    <rtsp>
        <!-- Other RTSP settings -->
        <http_notify>
            <on_connect>http://your-business-server.com/api/v1/rtsp/connect</on_connect>
            <on_play>http://your-business-server.com/api/v1/rtsp/play</on_play>
            <on_publish>http://your-business-server.com/api/v1/rtsp/publish</on_publish>
            <on_done>http://your-business-server.com/api/v1/rtsp/done</on_done>
            <notify_method>POST</notify_method>
        </http_notify>
    </rtsp>
    
    <rtmp>
        <!-- Other RTMP settings -->
        <http_notify>
            <on_connect>http://your-business-server.com/api/v1/rtmp/connect</on_connect>
            <on_play>http://your-business-server.com/api/v1/rtmp/play</on_play>
            <on_publish>http://your-business-server.com/api/v1/rtmp/publish</on_publish>
            <on_done>http://your-business-server.com/api/v1/rtmp/done</on_done>
            <notify_method>POST</notify_method>
        </http_notify>
    </rtmp>
    
    <!-- Other configurations (srt, http flv, etc.) -->
</config>

Callback Endpoints Explained

• <on_connect>: Called when a client first establishes a connection. Use it for IP-based access control or initial handshake validation.
• <on_play>: Called when a client requests to play a stream (PLAY command). Ideal for playback authentication.
• <on_publish>: Called when a client requests to publish a stream (PUBLISH command). Essential for ingest (push) authentication.
• <on_done>: Called when a play or publish session ends. Used for cleanup, logging session duration, or billing.
• <notify_method>: Specifies the HTTP method used for notifications. Defaults to POST. Also supports GET.

Callback Request Details

When a callback is triggered, the media server sends an HTTP request to your specified endpoint.

Request Method and Content-Type

• Method: Configured by <notify_method> (default: POST)
• Content-Type: application/x-www-form-urlencoded

POST Parameters Sent to Your Server

The following parameters are included in the request body (for POST) or query string (for GET):

Business Server Response

Your business server must process the incoming HTTP request and return an appropriate response.

Controlling Session Flow

For on_connect, on_play, and on_publish callbacks, the media server will suspend processing until it receives your response:

• If your server returns an HTTP 200 OK status code, the client session will be allowed to proceed.
• If your server returns any other status code (e.g., 403 Forbidden), the client session will be denied.

The on_done callback is informational; its HTTP response code is not checked by the server.

Example: Simple Authentication Endpoint (Node.js)

A basic Express.js endpoint that checks if the stream name starts with "private_" and requires a valid token:

// POST /api/v1/rtmp/publish
app.post('/api/v1/rtmp/publish', (req, res) => {
const { name, app, addr } = req.body;

// Check if it's a private stream
if (name.startsWith('private_')) {
// Extract token from URL (e.g., stream=private_live?token=abc123)
const urlParams = new URLSearchParams(new URL(req.body.url).search);
const token = urlParams.get('token');

if (!isValidToken(token)) {
  console.log(`Publish denied for ${name} from ${addr}`);
  return res.status(403).send('Forbidden');
}
}

console.log(`Publish allowed for ${name} (${app}) from ${addr}`);
res.status(200).send('OK');
});

Practical Applications

Leverage HTTP Notify for real-world scenarios:

• Push Stream Authentication: Use on_publish to validate tokens, keys, or user permissions before accepting an RTMP/RTSP push.
• Playback Authentication: Use on_play to check subscription status or geo-restriction rules before serving a live stream.
• Real-time Dashboard: Use all callbacks to populate a dashboard showing active streams, viewers, and ingest sources.
• Billing System: Use on_publish and on_done to track stream uptime for usage-based billing.
• Security Alerting: Use on_connect to flag connections from suspicious IPs or unexpected locations.