Auth0 Authentication API Webhooks Extension

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

To install and configure this extension:

1. Go to Auth0 Dashboard > Extensions, and select Auth0 Authentication API Webhooks. 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.

• 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.

• LOG_LEVEL: The minimal log level of events that you would like sent.

• LOG_TYPES: The events for which logs should be exported.

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

To view all scheduled jobs:

1. Go to the Auth0 Dashboard > Extensions, and select Installed Extensions.

2. Select Auth0 Authentication API Webhooks.

An example of the payload that will be sent:

{
  "date": "2016-02-25T13:42:08.791Z",
  "type": "f",
  "description": "Wrong email or password.",
  "connection": "My-Users",
  "client_id": "lIkP1Wn4qQPj56k9bE7fyMrbsaaHXd6c",
  "client_name": "Default App",
  "ip": "11.22.33.44",
  "user_agent": "Chrome 48.0.2564 / Mac OS X 10.11.3",
  "details":
   { "error":
      { "message": "Wrong email or password.",
        "oauthError": "Wrong email or password.",
        "type": "invalid_user_password" },
     "body":
      { "client_id": "lIkP1Wn4qQPj56k9bE7fyMrbsaaHXd6c",
        "username": "john@example.com",
        "password": "*****",
        "connection": "My-Users",
        "grant_type": "password",
        "scope": "openid",
        "device": "" },
     "qs": {},
     "connection": "My-Users" },
  "user_id": "",
  "user_name": "Default App",
  "strategy": "auth0",
  "strategy_type": "database",
  "_id": "49556539073893675610923042044589174982043486779166687234",
  "isMobile": false
}

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.