Hooks

Hooks are an important feature in Monibuca that allow triggering custom operations when specific events occur.

Feature Highlights

• Supports multiple event types
• Supports HTTP callbacks
• Supports custom scripts
• Supports asynchronous processing
• Supports retry mechanism

Configuration

Hooks can be configured in global configuration or under specific plugins. Global hooks apply to all related events, while plugin-specific hooks only apply to events generated by that plugin.

Global Configuration

In Monibuca's global configuration file, you can configure hooks as follows:

global:
  hook:
    # Hook configuration
    publish:  # Stream publish event
      url: http://your-server/hook  # Webhook URL
      method: POST  # HTTP method
      headers:  # Custom request headers
        Content-Type: application/json
      timeout: 5  # Timeout (seconds)
      retry: 3  # Retry count
      retryInterval: 1s  # Retry interval
    publish_end:  # Stream publish end event
      url: http://your-server/hook
      method: POST
    subscribe:  # Stream subscribe event
      url: http://your-server/hook
      method: POST
    subscribe_end:  # Stream subscribe end event
      url: http://your-server/hook
      method: POST
    server_keep_alive:  # Server heartbeat event
      url: http://your-server/hook
      method: POST
      interval: 60  # Heartbeat interval (seconds)

Plugin Configuration

You can also configure hooks for specific plugins to handle only events generated by that plugin:

rtmp:  # Plugin name
  hook:
    publish:
      url: http://your-server/rtmp-hook
      method: POST
      headers:
        Content-Type: application/json
      timeout: 5
      retry: 3
      retryInterval: 1s

Usage Examples

Configuring Multiple Event Hooks

global:
  hook:
    publish:
      url: http://your-server/publish-hook
      method: POST
      headers:
        Content-Type: application/json
      timeout: 5
      retry: 3
      retryInterval: 1s
    subscribe:
      url: http://your-server/subscribe-hook
      method: POST

Supported Event Types

• publish: Stream publish event
• publish_end: Stream publish end event
• subscribe: Stream subscribe event
• subscribe_end: Stream subscribe end event
• server_keep_alive: Server heartbeat event

Adding Hook Rules via API

POST /api/v1/hook/rules
Content-Type: application/json
{
    "event": "publish",
    "url": "http://your-server/hook",
    "method": "POST",
    "headers": {
        "Content-Type": "application/json"
    },
    "timeout": 5,
    "retry": 3,
    "retryInterval": 1,
    "interval": 60
}

Hook Event Data

publish Event

{
  "event": "publish",
  "streamPath": "live/stream",
  "args": {},
  "publishId": "pub_xxxxx",
  "remoteAddr": "127.0.0.1:12345",
  "type": "rtmp",
  "pluginName": "RTMP",
  "timestamp": 1623123456
}

publish_end Event

{
  "event": "publish_end",
  "streamPath": "live/stream",
  "publishId": "pub_xxxxx",
  "reason": "client disconnect",
  "timestamp": 1623123556
}

subscribe Event

{
  "event": "subscribe",
  "streamPath": "live/stream",
  "publishId": "pub_xxxxx",
  "subscriberId": "sub_xxxxx",
  "remoteAddr": "127.0.0.1:54321",
  "type": "http-flv",
  "args": {},
  "timestamp": 1623123656
}

subscribe_end Event

{
  "event": "subscribe_end",
  "streamPath": "live/stream",
  "subscriberId": "sub_xxxxx",
  "publishId": "pub_xxxxx",
  "reason": "client disconnect",
  "timestamp": 1623123756
}

server_keep_alive Event

{
  "event": "server_keep_alive",
  "timestamp": 1623123856,
  "streams": 10,
  "subscribers": 100,
  "publisherCount": 10,
  "subscriberCount": 100,
  "uptime": 3600
}

Important Notes

1. Ensure callback URLs are available
2. Set reasonable timeout values
3. Pay attention to request body size
4. Monitor hook execution
5. Handle failed callbacks promptly
6. Global hooks and plugin-specific hooks will trigger simultaneously

Common Issues

1. Hook Execution Failure
   • Check callback URL
   • Verify request format
   • Confirm network connection
2. Performance Issues
   • Optimize callback logic
   • Use asynchronous processing
   • Monitor response time
3. Retry Mechanism
   • Check retry configuration
   • Verify retry logs
   • Confirm retry results