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

About webhooks

Webhooks enable real-time event subscriptions within your Hanko project, automatically delivering event data to your server whenever authentication events occur. This facilitates user data synchronization and custom workflow automation. Create webhooks by specifying a callback URL and selecting events to monitor. When subscribed events occur, Hanko sends HTTP POST requests with event data to your specified endpoint. Your application can then process this data through a publicly accessible HTTPS endpoint.

High level overview of creating webhooks and handling webhook deliveries

Creating webhooks

Set up webhooks through these steps:
1

Access webhook settings

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

Configure your webhook

Click Create webhook, enter your callback URL, and select events for subscription. Review Events for complete event type information.
You can implement either a single webhook endpoint handling multiple events or separate webhooks for specific event types, depending on your architecture preferences.

Handling webhook deliveries

Process webhook deliveries through these steps:
1

Create callback endpoint

Implement a publicly accessible HTTP POST endpoint at your configured callback URL to receive webhook deliveries.
2

Parse webhook payload

Extract the webhook event payload containing event information and JWT-encoded event data.
3

Validate payload authenticity

Verify JWT signatures using your tenant’s .well-known endpoint to ensure deliveries originate from Hanko and remain uncompromised.
4

Decode JWT token

Parse the JWT to extract event data from the token payload. Event data structures vary by event type - see Event types and token payloads.
5

Process event data

Handle the extracted event data according to your application’s specific requirements.
Your server must return the complete certificate chain otherwise the request will fail.

Editing and removing webhooks

Manage existing webhooks through these steps:
1

Access webhook settings

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

Modify or delete webhooks

Find your webhook and click the three dots (...). Choose Edit to modify the callback URL or event subscriptions, or Delete to remove the webhook completely.

Events

Hanko offers various event types for subscription. Each event type determines the structure and content of the payload delivered to your callback URL.

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.