Auth0 Authentication API Webhooks

Auth0 Authentication API Webhooks

The Auth0 Authentication API Webhooks Extension is a scheduled job that allows you to use your own custom webhooks in conjunction with the Auth0 Authentication API. The extension will go through the audit logs and call the appropriate webhook if specific event(s) occur.

Configuring the Extension

To complete installation of this extension, click on the Auth0 Authentication API Webhooks box in the list of provided extensions on the Extensions page of the Management Portal. In the "Install Extension" window that then pops open, you will be asked to provide the following configuration variables:

  • Schedule: The frequency with which the job runs
  • Batch_Size: The amount of logs the extension will attempt to read and send on each execution. Extension could send multiple batches per run, depending on amount of time necessary to process. Maximum batch size is 100.
  • Webhook_URL: The URL of your webhook
  • Authorization: String to be added as Authorization header.
  • Send_as_Batch: If enabled, the extension will send the whole batch of logs to the webhook in a single request. Otherwise, extension sends logs one-by-one to webhook. Only disable 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: Log Checkpoint to start from.
  • Slack_Incoming_Webhook_URL: Extension can report statistics and possible failures to the Slack.
  • Slack_Send_Success: If enabled, extension will be sending messages on each run. Otherwise - only on fails.
  • Log_Level: The minimal log level of events that you would like sent
  • Log_Types: The specific events for which logs should be exported

Once you have provided the required pieces of information, click "Install" to finish installing the extension.

Using Your Installed Extension

You can view all scheduled jobs by clicking on the Auth0 Management API Webhooks line under the "Installed Extensions" tab.

Sample Payload

Here is 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": "",
  "user_agent": "Chrome 48.0.2564 / Mac OS X 10.11.3",
   { "error":
      { "message": "Wrong email or password.",
        "oauthError": "Wrong email or password.",
        "type": "invalid_user_password" },
      { "client_id": "lIkP1Wn4qQPj56k9bE7fyMrbsaaHXd6c",
        "username": "",
        "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

How to 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:

  1. Check the Logs section of the Dashboard 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