Create an Event Stream

By subscribing to events, and delivering them to a destination of your choice using event streams, you can facilitate a number of related use cases, including: 

  • Sending emails to new customers to welcome them or ask them to verify their email address.

  • Monitoring user lifecycle changes so that you can update CRM (customer relationship management) or billing systems.

You can create an event stream using either AWS EventBridge or webhooks. The sections below outline the setup process for both options.

Before you begin

Event streams are facilitated by the Auth0 Management API. Before you can set up an event stream, you need to create a machine-to-machine (M2M) application and authenticate with a Management API token. For more information, review Management API Access Tokens.

  1. Navigate to Dashboard > Applications > Applications and select Create Application.

  2. Enter a descriptive name for your application and choose Machine to Machine Applications. Then, select Create.

  3. Select the API you want to call from your application. In this case, use the Auth0 Management API.

  4. Choose the permissions that you want to be issued as part of your application's access token, then select Authorize. For testing purposes, select:

    • read:event_streams

    • create:event_streams

    • update:event_streams

    • delete:event_streams

    • read:event_deliveries

    • update:event_deliveries

    • create:users

  5. Navigate to the Settings tab to gather your Client ID, Client Secret, and Domain.

  6. Review Get Management API Access Tokens to retrieve and store your access token.

AWS EventBridge

The information below describes how you can create and enable an event stream using AWS EventBridge.

EventBridge prerequisites

To use AWS EventBridge for event streams, you will need the following:

  • AWS account

  • AWS IAM permissions

  • AWS EventBridge event bus

  • AWS account ID & region

Create an event stream (EventBridge)

Event streams allow you to capture real-time changes within your Auth0 tenant and send them to an external system for processing.

Before setting up an event stream, you need to identify the event types you want to monitor. Then, you will use your AWS account ID and region to set up your event stream, as demonstrated below. 

This example creates an event stream that subscribes to the user.created event, which triggers whenever a new user is registered in your tenant. 

auth0 events create --name ng-demo-eventbridge --type eventbridge --subscriptions "user.created" --configuration '{"aws_account_id":"<your-aws-account-id>","aws_region":"<your-aws-region>"}'

Was this helpful?

/

If successful, this call returns the following JSON with your event stream id. New event streams are disabled by default.

{
  "id": "est_8of6RXoM1997qikH7NS11h",
  "status": "disabled",
  "name": "ng-demo-eventbridge",
  "subscriptions": [
    {
      "event_type": "user.created"
    }
  ],
  "created_at": "2025-01-29T18:08:43.440Z",
  "updated_at": "2025-01-29T18:08:43.440Z",
  "destination": {
    "type": "eventbridge",
    "configuration": {
      "aws_account_id": "<your-aws-account-id>",
      "aws_region": "<your-aws-region>",
      "aws_partner_event_source": "default"
    }
  }
}

Was this helpful?

/

Enable the event stream (EventBridge)

After creating the event stream, you must enable it. Activating the stream allows it to begin publishing events to the configured AWS EventBridge instance.

To enable the stream, retrieve the event id returned above:

{...
  "id": "est_8of6RXoM1997qikH7NS11h",
  ...,
}

Was this helpful?

/

Then, make the following call:

auth0 events update <EVENT_STREAM_ID> --status enabled

Was this helpful?

/

The output from this call should confirm the event stream was updated to status:enabled, and the EventBridge configuration is in place. 

After the stream is active, you can test the event stream. For more information, review Event Testing, Observability, and Failure Recovery.

Webhooks

As an alternative to AWS EventBridge, you can use webhooks to facilitate event streams.

To get started, first set up a webhook handler to receive real-time notifications when a specific event occurs.  Then, you can create your event stream.

You can either create a basic webhook handler by following the instructions below, or you can use an existing service such as:

  • Vercel

  • Inngest

If you decide to use an existing service, you can proceed to Create an event stream (webhook). Otherwise, follow the instructions below to create your own basic webhook handler.

Webhook prerequisites

Ensure you have the following installed to properly write your webhook handler:

  • node.js

  • jq

  • npm

  • ngrok

Write the webhook handler

  1. Install express to your node_modules folder and your package.json dependencies.

  2. Install dotenv to your root directory to use a .env file for storing environment variables.

  3. Create a webhook.js file and insert the following code: 

    const express = require('express');
const bodyParser = require('body-parser');
require('dotenv').config(); // Load .env file

const app = express();
const PORT = 3000;

// Load the API token from environment variables
const API_TOKEN = process.env.API_TOKEN; // Access your API_TOKEN

// Parse JSON payloads
app.use(bodyParser.json());

// Webhook endpoint
app.post('/webhook', (req, res) => {
  // Check for the API token in the request headers
  const token = req.headers['authorization'];

  if (token !== `Bearer ${API_TOKEN}`) {
    // If the token is invalid, respond with a 401 Unauthorized
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // If the token is valid, process the webhook payload
  console.log('Webhook received:', JSON.stringify(req.body, null, 2));

  // Respond to the webhook sender
  res.sendStatus(204); // No Content
});

// Start the server
app.listen(PORT, () => {
  console.log(`Webhook handler running on http://localhost:${PORT}`);
});

    Was this helpful?

    /

  4. In the root of your project, create a .env file and add your API token using: 

    API_TOKEN=`openssl rand -hex 32`
echo "API_TOKEN=$API_TOKEN" > .env

    Was this helpful?

    /

  5. Start your server: 

    node webhook.js

    Was this helpful?

    /

  6. To test the Webhook, expose your webhook handler using a tool like ngrok: 

    ngrok http 3000

    Was this helpful?

    /
    This provides a public URL for your local webhook handler, for example: 
    http://localhost:3000

    Was this helpful?

    /

Create an event stream (webhooks)

Event streams allow you to capture real-time changes within your Auth0 tenant and send them to an external system for processing.

Before setting up an event stream, you need to identify the event types you want to monitor. You will then use your webhook handler to create an event stream, as demonstrated below.

This example creates an event stream that subscribes to the user.created event, which triggers whenever a new user is registered in your tenant. The event data is then forwarded to a webhook endpoint for further processing.

source .env # Make sure you are in the webhook directory where you created your .env file
WEBHOOK_URL="<ngrok URL>/webhook"

auth0 events create -n my-event1 -t webhook -s "user.created" -c '{"webhook_endpoint":"'"${WEBHOOK_URL}"'","webhook_authorization":{"method":"bearer","token":'"${API_TOKEN}"'"}}'

Was this helpful?

/

If successful, this returns the following JSON with your event stream id. New event streams are disabled by default to prevent data from being sent to your webhook endpoint without confirmation that the endpoint and configurations are correct.

{
  "id": "est_8of6RXoM1997qikH7NS11h",
  "status": "disabled",
  "name": "ng-demo-2",
  "subscriptions": [
    {
      "event_type": "user.created"
    }
  ],
  "created_at": "2025-01-29T18:08:43.440Z",
  "updated_at": "2025-01-29T18:08:43.440Z",
  "destination": {
    "type": "webhook",
    "configuration": {
      "webhook_endpoint": "https://example.com/webhook",
      "webhook_authorization": {
        "method": "bearer"
      }
    }
  }
}

Was this helpful?

/

Verify the event stream

After you create an event stream, you can verify that the event stream exists using the following command:

auth0 events show <EVENT_STREAM_ID>

Was this helpful?

/

Enable the event stream (webhooks)

The final step after creating the event stream is to enable it. This activates the stream and allows it to start publishing events to the configured webhook. To enable your event stream, you need the event_stream_id from the response of your API request that created the stream.  

auth0 events update <EVENT_STREAM_ID> --status enabled

Was this helpful?

/

The output from this call should confirm that the event stream was updated to status:enabled, and the webhook configuration is in place.

After the stream is active, you can test the event stream. For more information, review Event Testing, Observability, and Failure Recovery.

Learn more