Skip to main content

Webhooks

Dashboard access

The dashboard for all brands is at platform.nativeframe.com.

Accessing Webhook Configuration​

  1. Log into your Native Frame dashboard
  2. Navigate to "Projects" in the left sidebar
  3. Select your project
  4. Click "Event Webhooks" in the project menu

Creating a New Webhook​

  1. On the Event Webhooks page, you'll see a list of available event types
  2. Locate the "program-states" event, which is used for changes to stream states
  3. Click "Create Webhook" next to this event
Registration name vs. payload shape

The event you register is named program-states, but what your endpoint receives is the current program-states-v2 contract — a nested programs/tokens payload delivered as the top level of the JSON body. Only one program-states webhook is honored per project, and your response is acted on: see Webhook Authentication for the request/response contract, including why the response must mirror the request.

Configuring the Webhook​

On the webhook creation page, you'll configure the following:

Details​

  • Event Name: This will be pre-filled as "program-states"
  • Max Attempts: Set the maximum number of retry attempts if the initial webhook call fails. For critical auth checks, set this to at least 3.

Request​

  • URL: Enter the full URL of your authentication endpoint. This should be a secure (HTTPS) endpoint on your server that will receive the webhook payload and make auth decisions.
  • Method: the HTTP method for the webhook call. POST is required.
  • Headers: Add any custom headers your endpoint requires. Common headers include Authorization for API keys.

Response Validation​

  • Headers: If your endpoint returns specific headers to validate, enter them here.
  • Timeout: Set the maximum time (in seconds) to wait for a response from your endpoint. Balance this between reliability and user experience - 5 seconds is often a good starting point. Keep in mind the starting admission check is synchronous and fails closed: if your endpoint times out or errors, the broadcast is blocked.

Best Practices​

  1. Implement proper security measures on your webhook endpoint, such as API key validation.
  2. Keep your authentication logic fast to minimize stream startup delays.
  3. Log all webhook requests and responses for troubleshooting.
  4. Implement idempotency to handle potential duplicate webhook calls.
  5. Use HTTPS for your webhook URL to ensure data security.

Testing Your Webhook​

After creating the webhook:

  1. Return to the "Manage Streams" page
  2. Create a new stream or select an existing one
  3. Attempt to start the stream
  4. Monitor your webhook endpoint for incoming requests
  5. Check the Native Frame logs for any webhook-related issues

By following these steps, you'll have set up webhook-based events for your Native Frame streams. This allows for dynamic, real-time control over who can broadcast on your platform.