The Auth API enables you to connect 3rd party platform supporting a https request, to listen to realtime events. Webhooks are particularly useful for asynchronous events such as when a new API key is generated, first used, deleted or updated. We also support events for Auth Access and Project events.

​
Supported events

TypeEventTriggerNotes
API KeysCreatedFires the moment a new Key is createdAPI Key payloads will contain the API Key.
DeletedFires the moment the API is deleted
UpdatedFires any time the key is updatedThe metadata you choose to store on the key can be changed.
First UsedFires the first time the key is authenticated
Access KeysCreatedFires when a new access key is generatedAccess Key payloads will contain the Access Keys token.
DeletedFires when the access key is deleted
UpdatedFires when the access key is updated
ProjectsUpdatedFires when the project details get updated

​
What are webhooks?

A webhook enables the Auth API to push real-time notifications to your app. Auth API uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems. To learn more, see Auth API webhook events overview.

​
Steps to receive webhooks

You can start receiving event notifications in your app or in a 3rd platform by following these steps:

  • Identify the events you want to monitor and the event payloads to parse.
  • Create a webhook endpoint as an HTTP endpoint (URL) on your local server or with a 3rd party like Zapier.
  • Handle requests from Auth API by parsing each event object and returning 2xx response status codes.
  • Test that your webhook endpoint is working properly using our test connection feature.
  • If you are coding your own endpoint, deploy your webhook endpoint so it’s a publicly accessible HTTPS URL.
  • Register your publicly accessible HTTPS URL in the Auth API dashboard.

Creating Your first hook Head to your dashboard . Pick the project you want to tie your endpoint to and scroll to ‘Webhooks’. Click ’+ Create New Hook’ and follow the instructions.

​
Creating a webhook via the API

If you prefer a programmatic approach, you can create, update and delete webhooks (or any entity in The Auth API), head to our API docs - https://docs.theauthapi.com/

curl --location 'https://api.theauthapi.com/webhooks' \
--header 'x-api-key: REPLACE_WITH_YOUR_ACCESS_KEY_FOUND_IN_YOUR_ACCOUNT' \
--data '{
    "name": "only required fields webhook",
    "url": "https://webhook.site/3d224d6e-b525-45dd-9a60-5581df9264b9",
    "projectId": "REPLACE_WITH_YOUR_PROJECT_ID",
    "topics": [
        "api-key.created"
    ],
    "httpMethod": "POST",
    "status": "live"
}'

​
Building your own webhook endpoint

Creating a webhook endpoint is no different from creating any other page on your website. It’s an HTTP or HTTPS endpoint on your server with a URL. For local testing e.g. http://localhost:3000 consider using something like ngrok to route requests to your local machine. When it’s ready to launch, it must be running over HTTPS on a publically accessible domain. You can use one endpoint to handle several different event types at once or set up individual endpoints for specific events.

​
Testing your endpoint

When creating your webhook, you can test your endpoint. It’s important to test that the endpoint is up and running and receiving events successfully.

​
How to no-code an endpoint

The Auth API webhooks make it super simple to connect 3rd party applications like zapier.com, automate.io, stripe.com etc. to ensure you’re able to use the platform without any developer skills.

​
Security Best Practices

To read more about best practices and security, read this article: Best Practices for Webhooks.