Event Hooks#

go-rtmp fires hooks on RTMP lifecycle events, allowing external systems to react to stream activity in real-time. Hooks are asynchronous — they never block RTMP message processing.

Available Events#

Event Payload#

Every event is delivered as a JSON object:

{
  "type": "publish_start",
  "timestamp": 1705312222,
  "conn_id": "conn-abc123",
  "stream_key": "live/test",
  "data": {}
}

Some events include additional fields in data:

Webhook Hook#

Send HTTP POST requests to external URLs on specific events:

./rtmp-server \
  -hook-webhook "publish_start=https://api.example.com/on-publish" \
  -hook-webhook "publish_stop=https://api.example.com/on-unpublish" \
  -hook-webhook "auth_failed=https://alerts.example.com/auth"

The -hook-webhook flag format is event_type=url. It can be repeated for multiple event/URL pairs.

HTTP request details:

Shell Hook#

Execute scripts on specific events:

./rtmp-server \
  -hook-script "connection_accept=/opt/scripts/on-connect.sh" \
  -hook-script "publish_start=/opt/scripts/on-publish.sh"

The script receives event data as environment variables:

Example script:

#!/bin/bash
echo "Event: $RTMP_EVENT_TYPE"
echo "Stream: $RTMP_STREAM_KEY"
echo "Time: $RTMP_TIMESTAMP"

if [ "$RTMP_EVENT_TYPE" = "publish_start" ]; then
  curl -s -X POST "https://dashboard.example.com/api/streams" \
    -d "{\"key\": \"$RTMP_STREAM_KEY\", \"status\": \"live\"}"
fi

Stdio Hook#

Print events to stderr for log pipeline ingestion:

# JSON format (one JSON object per line)
./rtmp-server -hook-stdio-format json

# Environment variable format
./rtmp-server -hook-stdio-format env

This is useful for piping to log aggregators:

./rtmp-server -hook-stdio-format json 2>&1 | jq --unbuffered '.type'

Combining Hooks#

All three hook types can be used simultaneously:

./rtmp-server -listen :1935 \
  -hook-stdio-format json \
  -hook-webhook "publish_start=https://api.example.com/on-publish" \
  -hook-webhook "auth_failed=https://alerts.example.com/auth" \
  -hook-script "connection_accept=/opt/scripts/on-connect.sh" \
  -hook-timeout 30s \
  -hook-concurrency 10

Each event fires all matching hooks in parallel.

Configuration#

The concurrency limit uses a bounded semaphore. When the pool is full, new hooks queue in goroutines until a slot opens. This prevents hook storms from consuming unlimited resources.

Execution Model#

• Hooks execute asynchronously — they never block RTMP message processing
• Each hook runs in its own goroutine with a timeout context
• A bounded worker pool (semaphore channel) limits concurrency
• Errors are logged at ERROR level; successes at DEBUG level
• Execution duration is tracked and logged

Use Cases#