RTSP Server HTTP Notify Guide | Webhook & Callback Integration

What is HTTP Notify?

HTTP Notify (also known as Webhooks or Callbacks) allows your RTSP server to communicate with external HTTP services in real-time. It's a powerful mechanism for:

Authentication: Validate clients before allowing CONNECT, PLAY, or PUBLISH.
Event Notification: Get notified when streams start/stop, enabling real-time monitoring.
Access Control: Dynamically grant or deny access based on your business logic.
Logging & Analytics: Track user activity and system events.

The RTSP server sends an HTTP request to your configured endpoint when specific events occur.

Configuration

Enable HTTP Notify by modifying the rtspserver.cfg file.

rtspserver.cfg

<config>
    <!-- HTTP Notify Callbacks -->
    <on_connect>http://your-webhook.com/connect</on_connect>
    <on_play>http://your-webhook.com/play</on_play>
    <on_publish>http://your-webhook.com/publish</on_publish>
    <on_done>http://your-webhook.com/done</on_done>
    
    <!-- HTTP Method: POST (default) or GET -->
    <notify_method>POST</notify_method>
    <!-- ... other settings -->
</config>

Callback Endpoints & Parameters

For each event, the RTSP server sends an HTTP request (POST by default) with form data (application/x-www-form-urlencoded). The processing of the RTSP command is suspended until the HTTP request returns.

1. on_connect

Triggered when a client initiates a connection.

Parameter	Description	Return Requirement
`protocol=rtsp`	Always "rtsp"	Return HTTP 200 for success. Any other code (403, 500) will reject the connection.
`call=connect`	Indicates the event type
`addr`	Client's IP address
`url`	Full URL requested by the client
`name`	Stream name (if applicable)
`clientid`	Unique RTSP session ID

2. on_play

Triggered when a client issues a PLAY command.

Parameter	Description	Return Requirement
`protocol=rtsp`	Always "rtsp"	Return HTTP 200 for success. Any other code will reject the play request.
`call=play`	Indicates the event type
`addr`	Client's IP address
`url`	Full URL requested by the client
`name`	Stream name being played
`clientid`	Unique RTSP session ID

3. on_publish

Similar to on_play, but triggered when a client issues a PUBLISH command (for push streaming).

Parameter	Description	Return Requirement
`protocol=rtsp`	Always "rtsp"	Return HTTP 200 for success. Any other code will reject the publish request.
`call=publish`	Indicates the event type
`addr`	Client's IP address
`url`	Full URL for publishing
`name`	Stream name to be published
`clientid`	Unique RTSP session ID

4. on_done

Triggered when a PLAY or PUBLISH session terminates (gracefully or forcibly).

Parameter	Description	Return Note
`protocol=rtsp`	Always "rtsp"	The HTTP status code is not checked. This is for notification only.
`call=done`	Indicates the event type
`addr`	Client's IP address
`url`	URL of the ended session
`name`	Stream name that ended
`clientid`	Unique RTSP session ID

HTTP Method

The <notify_method> parameter determines how the HTTP request is sent.

POST (Default): Uses POST method with application/x-www-form-urlencoded content type. Recommended for security and reliability.
GET: Appends parameters to the URL as query string. Simpler but less secure and has URL length limits.

Best Practices

Use HTTPS: Always serve your webhook endpoints over HTTPS to protect the data in transit.
Validate Source: Verify the IP address of the incoming request to ensure it comes from your RTSP server.
Handle Errors Gracefully: Your webhook endpoint should be robust and handle unexpected input or network issues.
Keep Response Fast: Since RTSP command processing is blocked, ensure your HTTP endpoint responds quickly to avoid client timeouts.
Secure Your Logic: Use the callback to implement rate limiting, authentication, and authorization checks.

Happytimesoft