Create Custom Log Streams Using Webhooks
Webhooks provide a way for events to be delivered to an external web server. Auth0 offers several integrations that automatically push events to third-party log management and analysis systems. If however your third-party system isn't supported, you can easily set up a custom webhook integration.
You can only subscribe one payload URL per webhook configuration, but you can use the same URL for multiple streams. The payload will be delivered in JSON lines format. Keep that in mind while consuming the logs in your webhook configuration.
When Auth0 creates a log entry for your tenant, a copy is sent to the URL using an HTTP POST request. You will need to build an API that provides a single /api/logs route that accepts POST requests. When any log event occurs, it will be sent to this endpoint. Then, if the request is formatted properly, the log events for failures will be parsed and sent to the URL you choose. Please note that self-signed HTTP certs are not supported.
Go to Dashboard > Monitoring > Streams and click Create Stream.
Select Custom Webhook and enter a unique name for your new stream.
Configure the following settings.
Setting Description Name A unique display name to distinguish this integration from other integrations. Payload URL The URL where the event payloads are sent as HTTP POST requests. Authorization Token (Optional) Set in the Authorization header of the request if provided. Content Type The media type of the payload that will be delivered to the webhook. Content Format Recieve data in JSON lines, arrays, or objects. Click Save.
Test configuration
When Auth0 writes the next tenant log, you'll receive a copy of that log event as a POST request at the Payload URL you provided.
Delivery attempts and retries
Auth0 events are delivered to your server via a streaming mechanism that sends each event as it is triggered in our system. If your server is unable to receive the event, we will retry up to three times to deliver the event; otherwise, we will log the failure, and you will be able see it in the Health tab for your log stream.
Troubleshoot Webhooks
If your webhook isn't working, it can be difficult to troubleshoot and determine what is causing the issue. Webhooks are asynchronous, so testing them can involve you triggering the webhook, waiting, and then checking the response (assuming that you did receive a response).
However, there are certainly alternatives to the inefficient process we detailed above. While full details of how to troubleshoot a particular webhook is outside the scope of this article, here are some steps you can take to debug:
Check Auth0 Dashboard > Monitoring > Logs for helpful messages.
Analyze the requests your webhook is making using a tool like Hookbin or Mockbin.
Mock requests using cURL or Postman.
Test your webhook code locally using something like localtunnel or ngrok.
Use a tool like Runscope or Assertible to watch the whole execution flow.