Event Testing, Observability, and Failure Recovery
The following sections provide information about testing event streams and managing events.
Test the event stream
After you create and enable an event stream using either AWS EventBridge or webhooks, you can test the new stream. Currently, Auth0 does not support sending events to disabled event streams.
To test your event stream, first create a user for your application by running the following with your preferred credentials:
auth0 users create # follow prompts to create a test user
Was this helpful?
curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-X POST https://$TENANT/api/v2/users \
-d '{
"email": "nick-testing-21@example.com",
"password": "Password123!",
"connection": "Username-Password-Authentication"
}'
Was this helpful?
After the user is created, it should trigger the user.created
event in your event stream and return a response. In this example, webhooks are used to facilitate the event stream.
Webhook received: {
"id": "evt_6SfwXrtm8nVcjzzNCFFH1L",
"source": "urn:auth0:",
"specversion": "1.0",
"type": "user.created",
"time": "2025-02-02T17:56:01.573Z",
"data": {
"object": {
"created_at": "2025-02-02T17:56:01.566Z",
"email": "nick-testing-21@example.com",
"email_verified": false,
"identities": [
{
"connection": "Username-Password-Authentication",
"isSocial": false,
"provider": "auth0",
"user_id": "679fb1b1e809445f129bc18d"
}
],
"name": "nick-testing-21@example.com",
"nickname": "nick-testing-21",
"picture": "test.png",
"updated_at": "2025-02-02T17:56:01.566Z",
"user_id": "auth0|679fb1b1e809445f129bc18d"
}
},
"a0tenant": "acme",
"a0stream": "est_38ANnv8pQhqsZrX2VFbftv"
}
Was this helpful?
You can list the event delivery failures for a specific event stream by running:
auth0 api get event-streams/$EVENT_STREAM_ID/deliveries
Was this helpful?
curl -s -H "Authorization: Bearer $TOKEN" \
"https://$TENANT/api/v2/event-streams/${EVENT_STREAM_ID}/deliveries" | jq .
Was this helpful?
If an empty delivery failure array is returned, your event stream is running correctly.
Observability
To ensure the reliability of event streams, implement a monitoring process that periodically checks for delivery failures and triggers alerts when necessary.
Polling Deliveries endpoint
Poll the Deliveries endpoint every 5 minutes to check for failed events. Use the following API call to fetch recent event deliveries:
auth0 api get event-streams/$EVENT_STREAM_ID/deliveries
Was this helpful?
curl -s -H "Authorization: Bearer $TOKEN" \
"https://$TENANT/api/v2/event-streams/${EVENT_STREAM_ID}/deliveries" | jq .
Was this helpful?
If failures are detected:
Log the failed event details.
Alert the appropriate team or system to review and diagnose the issue.
Recovery
If failures occur, use the Redelivery API to attempt event delivery again.
Redeliver a single failed event
To retry a specific failed event, use:
EVENT_ID=<your event id>
auth0 api POST event-streams/$EVENT_STREAM_ID/redeliver/$EVENT_ID --data '{}'
Was this helpful?
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
"https://<your-domain>/api/v2/event-streams/$EVENT_STREAM_ID/redeliver/$EVENT_ID"
Was this helpful?
Batch redelivery of failed events
To retry all failed events in the event stream:
auth0 api POST event-streams/$EVENT_STREAM_ID/redeliver --data '{}'
Was this helpful?
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
"https://<your-tenant>.auth0.com/api/v2/event-streams/<event_stream_id>/redeliver"
Was this helpful?
Auto-disable mechanism
Auth0 automatically disables an event stream if excessive failures occur.
Condition | Action taken |
---|---|
500 consecutive failures | Event stream is disabled automatically. |
5000 total failures | Event stream is disabled automatically. |
If an event stream is auto-disabled, you must use the Redelivery API to process any failed events.
The event stream cannot be manually re-enabled until the total failure count drops below 5000.
Once the number of failures is reduced, you can re-enable the stream via API.