Webhooks

Lunar Stream uses webhooks to notify your server about stream events.

Push Auth Webhook

When a broadcaster attempts to push an RTMP stream, the media server sends a webhook to validate the push token.

Webhook Flow

┌────────────┐     RTMP Push      ┌─────────────┐
│ Broadcaster│ ─────────────────▶ │ Media Server│
└────────────┘                    └──────┬──────┘
                                         │
                                         │ POST /push-auth
                                         ▼
                                  ┌─────────────┐
                                  │ Lunar Stream│
                                  │     API     │
                                  └──────┬──────┘
                                         │
                                         │ Validate Token
                                         ▼
                                  ┌─────────────┐
                                  │  Response   │
                                  │ {code: 0}   │
                                  └─────────────┘

Webhook Payload

The media server sends this payload to validate the stream:

{
  "app": "live",
  "stream": "ee04affe2a669854052102fe762bd715",
  "params": "pushToken=eyJhbGciOiJSUzI1NiIs...",
  "ip": "123.45.67.89",
  "port": 54321
}

Response Format

Success (Allow streaming):

{
  "code": 0,
  "msg": "success"
}

Failure (Reject streaming):

{
  "code": -1,
  "msg": "Invalid push token"
}

Stream Status Updates

Your application can poll the API to check stream status changes:

async function monitorStreamStatus(streamKey, onStatusChange) {
  let lastStatus = null;
  
  setInterval(async () => {
    const response = await fetch(
      `https://api.lunarstream.kozow.com/api/v1/livestreams/stream-info/${streamKey}`
    );
    const { data } = await response.json();
    
    if (data.status !== lastStatus) {
      onStatusChange(data.status, lastStatus);
      lastStatus = data.status;
    }
  }, 5000); // Poll every 5 seconds
}

// Usage
monitorStreamStatus('ee04affe2a669854052102fe762bd715', (newStatus, oldStatus) => {
  console.log(`Stream status changed: ${oldStatus} -> ${newStatus}`);
  
  if (newStatus === 'STARTED') {
    notifyViewers('Stream is now live!');
  } else if (newStatus === 'ENDED') {
    notifyViewers('Stream has ended');
  }
});

Stream Events

Event	Description
READY_FOR_USE	Stream created, waiting for broadcaster
STARTED	Broadcaster connected, stream is live
ENDED	Broadcaster disconnected
TOKEN_EXPIRED	Push token expired

Best Practices

1. Implement retry logic for webhook failures
2. Validate webhook signatures if implemented
3. Use polling sparingly to avoid rate limits
4. Cache stream status to reduce API calls