Skip to main content

Webhook Authentication for Streaming

Introduction​

Native Frame's webhook functionality provides a powerful alternative to JWT-based authentication for stream authorization. This guide explains how to use webhooks to authenticate and control streams, offering real-time, dynamic control over stream access and management.

Webhooks are particularly useful when you need constant reference to your system as the source of truth for authentication and authorization decisions. This approach allows for more granular control and real-time updates to stream permissions.

How It Works​

Native Frame's webhook system sends HTTP POST requests to a specified endpoint on your server whenever certain events occur or authentication decisions need to be made. Your server then responds with instructions on how to handle the stream or viewer.

Key Concepts​

  1. Program: A container for one or more streams. Programs allow for bulk operations on multiple streams.
  2. Stream: An individual video stream within a program.
  3. Token: Represents a user's authentication and can be associated with either a broadcaster or a viewer.

Webhook Request Structure​

When Native Frame needs to make an authentication decision, it will send a POST request to your specified endpoint. The request body will contain information about the programs and streams that need authentication.

Here's a simplified example of a webhook request:

{
  "programs": {
    "program1": {
      "streams": {
        "stream1": {
          "token": {
            "value": "user_token_123",
            "type": "token",
            "action": "creating"
          },
          "viewTokens": [
            {
              "value": "viewer_token_456",
              "type": "token",
              "action": "joining"
            }
          ]
        }
      }
    }
  }
}

Token Actions​

The action field in a token object indicates what the user is attempting to do:

  • hls-auth: Authenticating for HLS playback
  • joining: Attempting to join a stream for WebRTC playback
  • creating: Attempting to create (broadcast) a stream
  • polling: Currently viewing a stream

Webhook Response Structure​

Your server should respond to the webhook with instructions on how to handle each program and stream. Here's a simplified example response:

{
  "programs": {
    "program1": {
      "stop": false,
      "needAuth": true,
      "streams": {
        "stream1": {
          "stop": false,
          "needAuth": true,
          "token": "validated_broadcaster_token",
          "appData": {
            "user.id": "broadcaster123",
            "user.name": "John Doe",
            "user.scope": "broadcaster"
          },
          "viewTokens": {
            "viewer_token_456": {
              "stop": false,
              "appData": {
                "user.id": "viewer456",
                "user.name": "Jane Smith",
                "user.scope": "viewer"
              }
            }
          }
        }
      }
    }
  }
}

Key Response Fields​

  • stop: Set to true to stop a program or stream.
  • needAuth: Set to true to indicate that future tokens for this program or stream should be forwarded to your webhook for authentication.
  • appData: Use this to pass additional information about the user. The user.id, user.name, and user.scope fields are especially important.
Important: WebRTC Scopes and User Identification

When using webhooks with WebRTC streams, it's crucial to set the correct information in the appData field:

Scopes for SFU management:

"appData": {
  "user.scope": "broadcaster"  // or "viewer", "private-broadcaster", "private-viewer"
}

The user.scope field is essential for the Selective Forwarding Unit (SFU) to properly identify and manage participants. User identification for frontend use:

"appData": {
  "user.id": "user123",
  "user.name": "John Doe"
}

The user.id and user.name fields are primarily used for identifying users in the frontend application. They don't affect stream permissions but can be useful for displaying user information or managing user interactions in your application's interface.

Using private-broadcaster or private-viewer for user.scope will prevent users with standard broadcaster or viewer JWT scopes from accessing the stream, providing an additional layer of security.

Handling Viewer Tokens​

When a viewer attempts to join a stream using a token that isn't a JWT, Native Frame will pass this token to your webhook for validation. This allows you to implement custom authentication logic for viewers.

Important: Webhook tokens must be unique.

Webhook tokens must be unique and cannot be reused. If a token is reused, the first user who used the token will be kicked from the stream. This includes the broadcaster!

If your webhook response indicates that a viewer should be stopped (by setting stop: true for their token), Native Frame will kick the viewer off the stream.

Stopping Streams​

You can stop an entire stream by setting stop: true in the stream's response object. This is useful for scenarios where you need to immediately terminate a broadcast due to policy violations or other reasons.

Implementing Webhook Authentication​

  1. Set up an endpoint on your server to receive webhook POST requests.
  2. Implement logic to validate tokens and make authorization decisions.
  3. Return a properly structured response indicating whether to allow or deny access, and whether to stop streams or kick viewers.
  4. Configure your Native Frame project to use your webhook endpoint for authentication.

Testing Webhook Integration Locally​

Testing webhook integration locally can be challenging since webhooks require a publicly accessible URL. However, you can use a tool like ngrok to expose your local server to the internet for testing purposes.

  1. Install ngrok from https://ngrok.com/
  2. Start your local server (e.g., on port 3000)
  3. Run ngrok to create a tunnel to your local server: 
       ngrok http 3000
  4. ngrok will provide a public URL (e.g., https://1234abcd.ngrok.io)
  5. Configure your Native Frame project to use this ngrok URL as the webhook endpoint
  6. You can now test your webhook integration with your local server

Remember to monitor the ngrok console and your local server logs for incoming requests and any potential errors during testing.

Example Server Implementation

Checkout the Server-Side Setup guide for a simple implementation of a web server that can be used to test webhook authentication.

Best Practices​

  1. Implement proper security measures on your webhook endpoint, such as requesting signature validation.
  2. Ensure your webhook handler responds quickly to avoid timeouts.
  3. Implement proper error handling and logging in your webhook handler.
  4. Use HTTPS for your webhook endpoint to ensure secure communication.
  5. Consider implementing a retry mechanism in case your server is temporarily unavailable.

By leveraging webhook authentication, you can create a highly dynamic and secure streaming experience that integrates seamlessly with your existing user management system. This approach offers real-time control and flexibility that goes beyond what's possible with static JWT authentication.