Events Best Practices

For best results when developing event streams, Auth0 recommends adhering to the best practices compiled below. These guidelines can help reduce friction, increase efficiency, and promote a best-in-class eventing journey.

On receiving an event, respond with an HTTP 2XX OK (e.g., 200OK, 202 Accepted, 204 No Content)  to signal that the event was successfully delivered. Without this response, Auth0 considers the event delivery a failure and will retry in accordance with the behavior described under System behavior during failed event deliveries.

To avoid scalability issues, configure your handler to process incoming events with an asynchronous queue. If processing events synchronously, any large spike in webhook deliveries (for example, during the beginning of the month when all subscriptions renew) may overwhelm your endpoint hosts. Asynchronous queues allow you to process the concurrent events at a rate your system can support.

Webhook endpoints may occasionally receive the same event more than once. You can guard against duplicated event receipts by logging the event IDs you’ve processed.

Auth0 does not guarantee that events are delivered in the same sequence that they are generated. For example, when a user is created and then immediately updated such that another user is linked to it, you may receive:

• user.updated (for User 1)

• user.created (for User 1)

• user.deleted (for User 2)

• user.updated (for User 2)

To ensure you do not overwrite your data with stale information, check the timestamp of the incoming webhook data against the timestamp of the data in your system. Each data.object in the payload includes a created_at field and an updated_at field.

Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events (or all events) puts undue strain on your server and is not recommended.

You can change the events that a webhook endpoint receives by updating event streams.

Currently, Auth0  only allows four total attempts, including the initial attempt and three retries with exponential backoff (1s, 2s, 4s).  If you receive a 4XX, the event fails immediately with no retries, as retrying is unlikely to change the response.  

If your endpoint still does not respond successfully after this time, the event is marked as failed, and Auth0 will no longer retry sending it. For more information on failing events, review Event Stream Testing, Observability, and Failure Recovery.

Event streams are automatically disabled in the following scenarios:

• Auth0 receives 500 failures (i.e., anything other than a 2XX) in a row. 

• The Event Stream reaches 5000 total failed deliveries.

• Auth0 receives three consecutive delivery attempt failures (i.e., anything other than a 2XX). 

  • If you wish to permit more delivery attempt failures, submit a support ticket requesting the number of failures you wish to permit, and Auth0 will review your request. 

• Event Types
• Create an Event Stream
• Event Testing, Observability, and Failure Recovery