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
  • Auth0_Domain: The domain of your Auth0 app
  • Auth0_Global_Client_ID: The Client ID of your Auth0 app
  • Auth0_Global_Client_Secret: The Client Secret of your Auth0 app
  • Auth0_API_Endpoints: The specific Auth0 Management API endpoints you want to monitor/call
  • Webhook URL: The URL of your webhook
  • Webhook_Concurrent_Calls: The maximum number of concurrent calls that will be made to your webhook
  • 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": "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
}

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