Auth0 Management API Webhooks Extension

The Auth0 Management API Webhooks extension allows you to use your own custom webhooks in conjunction with the Auth0 Management API. The extension goes through the audit logs and calls the appropriate webhook if specific events occur.

To install and configure this extension:

1. Navigate to the Auth0 Dashboard > Extensions, and click the Auth0 Management API Webhooks box. The Install Extension window opens.

2. Set the following configuration parameters:

• Schedule: The frequency with which the job runs.

• BATCH_SIZE: The number of logs the extension will attempt to read and send each time it executes. Maximum is 100. The extension could send multiple batches per run, depending on the amount of processing time necessary.

• Auth0_API_Endpoints: The specific Auth0 Management API endpoints you want to monitor.

• Webhook_URL: The URL of your webhook.

• Authorization: The string to be added as the Authorization header.

• Send_as_Batch: Choose whether to send the whole batch of logs to the webhook in a single request. When disabled, the extension sends logs individually to the webhook. Only disable this if your webhook does not support batched messages.

• Webhook_Concurrent_Calls: The maximum number of concurrent calls that will be made to your webhook.

• START_FROM: The checkpoint ID of the log from which you want to start reading.

• SLACK_INCOMING_WEBHOOK_URL: The specific Slack webhook to which you want to send reports from the extension.

• SLACK_SEND_SUCCESS: Choose whether to send verbose notifications to Slack. Useful for troubleshooting. When enabled, the extension will send messages on each run; otherwise, it will send messages only on fails.

After you provide this information, click the Install button to finish installing the extension.

To view all scheduled jobs:

1. Navigate to Auth0 Dashboard > Extensions, and select Installed Extensions.

2. Select Auth0 Management API Webhooks.

An example of the payload that will be sent is as follows:

{
   "date":"2017-09-06T07:33:10.424Z",
   "request":{
      "method":"post",
      "path":"/api/v2/clients",
      "query":{

      },
      "body":{
         "name":"auth0-webhooks"
      },
      "channel":"https://manage.auth0.com/",
      "ip":"127.0.0.1",
      "auth":{
         "user":{
            "user_id":"auth0|56541aaa73ec334341338bbe",
            "name":"John Doe",
            "email":"johndoe@gmail.com"
         },
         "strategy":"jwt",
         "credentials":{
            "jti":"0615b65ee0b5b29f4517153d2a943463",
            "scopes":[
               "read:clients",
               "create:clients",
               "update:clients",
               "delete:clients"
            ]
         }
      }
   },
   "response":{
      "statusCode":201,
      "body":{
         "callback_url_template":false,
         "client_id":"vRrHLFDHKSMEVLBmyV3UCoBBgsIPZBr5",
         "custom_login_page_on":true,
         "global":false,
         "name":"auth0-webhooks",
         "tenant":"test-tenant"
      }
   }
}

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:

1. Check Auth0 Dashboard > Monitoring > Logs for helpful messages.

2. Analyze the requests your webhook is making using a tool like Hookbin or Mockbin.

3. Mock requests using cURL or Postman.

4. Test your webhook code locally using something like localtunnel or ngrok.

5. Use a tool like Runscope or Assertible to watch the whole execution flow.