This feature is only available in the Pro or Enterprise plan.

About webhooks

Webhooks allow you to subscribe to events within a Hanko project and automatically receive data deliveries to your server/application whenever those events take place. This allows you to, for example, synchronize user data between your application(s) and Hanko.

To create a webhook you specify a callback URL and subscribe to events that occur in your Hanko project. Once an event that your webhook is subscribed to occurs, Hanko will send an HTTP POST request with data about the event to the URL that you specified. If your application provides a publicly available HTTP endpoint listening for webhook deliveries at the configured callback URL, it can react and process webhook data.

High level overview of creating webhooks and handling webhook deliveries

Creating webhooks

To create a webhook:

1

Access your project's webhook settings

Log in to the Hanko Cloud Console, select your organization and project and navigate to Settings > Webhooks.

2

Create a webhook

Click Create webhook. Enter a callback URL and select the events that you want to subscribe to. See Events for more information on the events you can subscribe to.

You are free to choose whether you create a single webhook with one HTTP endpoint processing multiple events or multiple webhooks with more than one HTTP endpoint handling specific events or event groups.

Handling webhook deliveries

To handle webhook deliveries:

1

Create callback URL endpoint

In order to handle webhook deliveries, your application must provide a publicly available HTTP POST endpoint listening for webhook deliveries at the configured callback URL.

2

Parse webhook payload

Once you have an endpoint set up you need to extract the webhook event payload. It contains information about which event occurred and the actual event data encoded in a JSON Web Token (JWT).

3

Validate webhook payload

To ensure that your application only processes webhook deliveries that were sent by Hanko and to ensure that the delivery has not been tampered with, you should validate the JWT’s signature before processing the delivery further. You can use the JSON Web Key Set available through your tenant’s .well-known endpoint to do so.

4

Parse webhook payload token

The JWT contained in the webhook payload must be parsed to obtain the event data from the token payload. The structure of the event data may differ from event type to event type. For more information, see Event types and token payloads.

5

Process event data

Once you have extracted the event data from the token you can process it according to your application’s needs.

Your server must return the complete certificate chain otherwise the request will fail.

Editing/removing webhooks

You can edit or remove configured webhooks. To do so:

1

Access your project's webhook settings

Log in to Hanko Cloud, select your organization and project and navigate to Settings > Webhooks.

2

Edit/delete a webhook

Locate the desired webhook and click on the three dots (...). Select Edit to change either the callback URL of the webhook or the events to subscribe to. Select Delete to remove the webhook entirely.

Events

There are different types of events you can subscribe to. The event type determines the contents of the event payload (i.e. the body content of the request to your callback URL in response to an event occurrence).

Event payload

The structure of the event payload is the same across all event types. It contains the event type and the event data in the form of a JSON Web Token (JWT).

Event types and token payloads

Events are structured hierarchically with some events subsuming the occurrence of multiple (“sub”)-events. These types of events do not actually appear as the value for the event property in the webhook event payload. Subscribing to these types of events when creating a webhook is a convenient way to group certain event types and allows you to structure your callback endpoints around these groups.

A webhook’s event data is encoded as a JWT in the webhook’s callback request body. You need to parse the token to access the token’s payload which contains the actual event data (see Handling webhook deliveries for an example).

user

Subscribing to this event implies subscription to the following events: user.create, user.delete, user.login, user.udpate.email.create, user.update.email.delete, user.update.email.primary, user.update.password.update user.update.username.create, user.update.username.delete, user.update.username.update

user.create

This event is triggered when a new user is created.

user.delete

This event is triggered when a user is deleted.

user.login

This event is triggered when a user logs in.

user.update

Subscribing to this event implies subscription to the following events: user.udpate.email.create, user.update.email.delete, user.update.email.primary, user.update.password.update user.update.username.create, user.update.username.delete, user.update.username.update

user.update.email

Subscribing to this event implies subscription to the following events: user.udpate.email.create, user.update.email.delete, user.update.email.primary

user.update.email.create

This event is triggered when an email is created for a user.

user.update.email.delete

This event is triggered when a user’s email is deleted.

user.update.email.primary

This event is triggered when a user’s email is set as the primary email.

user.update.password.update

This event is triggered when a user updates their password through the profile.

user.update.username

Subscribing to this event implies subscription to the following events: user.update.username.create, user.update.username.delete, user.update.username.update

user.update.username.create

This event is triggered when a username is created for a user.

user.update.username.delete

This event is triggered when a user’s username is deleted.

user.update.username.update

This event is triggered when a user’s username is updated.

email.send

This event is triggered when an email is sent. Subscribe to this event if you want to send customized emails instead of emails based on built-in templates. See Custom Emails for more information.