Best Practices

For best results when developing event streams, we recommend adhering to some best practices compiled below. Although not comprehensive, this should help reduce friction, increase efficiency, and help provide a best-in-class eventing journey.

On receiving an event, you should respond with an HTTP 2XX OK (e.g., 200OK, 202 Accepted, 204 No Conent)  to signal that the event was successfully delivered. Otherwise, Auth0 considers the event delivery a failure and will retry up to 12 times. You do not need to signal to Auth0 whether or not the event was processed successfully.

Do not attempt to process the event before responding.  If you do, your system may not be able to handle a spike of requests.  

Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by logging the event IDs you’ve processed not processing already-logged events.

Auth0 does not guarantee that events are delivered in the same sequence that they are generated. For example, when syncing directory events you may receive:

• Organization.created

• User.created

• Organization.member_added

Your endpoint should handle use cases when these events are delivered out of order. Each event includes the full payload of the objects involved, so you can perform an upsert using the payload data.

It is also possible that event data can be stale due to a retry of an older event being delivered after a newer event for the same object. Therefore, we recommend checking the timestamp of the incoming webhook data against the timestamp of the data in your system to ensure you do not overwrite your data with stale data. Each 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 in the Dashboard or with the API.

Configure your handler to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries (for example, during the beginning of the month when all subscriptions renew) might overwhelm your endpoint hosts.

Asynchronous queues allow you to process the concurrent events at a rate your system can support.

If your endpoint fails to respond to a webhook request with a 2XX response, Auth0 automatically retries the event with exponential back-off for up to [Placeholder] days.  If your endpoint still fails to respond successfully after this time, the event will be marked as failed, and we will no longer retry sending it. 

Event Streams will be disabled when Auth0 receives three consecutive delivery attempt failures (anything other than a 2XX).  If you wish to permit more delivery attempt failures, submit a support ticket request the number of failures you wish to permit, and Auth0 will review your request.