Hanko Webhooks Guide:About Hanko:Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.What This Guide Covers: This guide demonstrates how to implement webhooks with Hanko to receive real-time notifications about authentication events. You’ll learn to create webhook endpoints, validate payloads, and process user lifecycle and email events for data synchronization and custom workflows.Key Technologies:
- HTTP Webhooks
- JSON Web Tokens (JWT)
- Webhook Signature Verification
- Event Processing
- RESTful APIs
- Hanko Cloud Console
- Hanko Pro or Enterprise plan subscription
- Public HTTPS endpoint for webhook delivery
- Understanding of HTTP request handling
- JWT verification knowledge
- Server-side development capabilities
- Create webhook subscriptions in Hanko Cloud
- Build webhook endpoint for event processing
- Validate JWT signatures for security
- Parse and process different event types
- Handle user lifecycle events (create, update, delete)
- Process email send events for custom delivery
- Implement error handling and retry logic
This feature is only available in the Pro or Enterprise plans.
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.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.
Example (Javascript)
Example (Javascript)
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 payload example
Event payload example
user.create
Event payload properties
Event payload properties
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 theevent 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.create' token payload example
'user.create' token payload example
user.delete
This event is triggered when a user is deleted.'user.delete' token payload example
'user.delete' token payload example
user.login
This event is triggered when a user logs in.'user.login' token payload example
'user.login' token payload example
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.create' token payload example
'user.update.email.create' token payload example
'user.update.email.create' token payload properties
'user.update.email.create' token payload properties
user.update.email.delete
This event is triggered when a user’s email is deleted.'user.update.email.delete' token payload example
'user.update.email.delete' token payload example
'user.update.email.delete' token payload properties
'user.update.email.delete' token payload properties
user.update.email.primary
This event is triggered when a user’s email is set as the primary email.'user.update.email.primary' token payload example
'user.update.email.primary' token payload example
'user.update.email.primary' token payload properties
'user.update.email.primary' token payload properties
user.update.password.update
This event is triggered when a user updates their password through the profile.'user.update.password.update' token payload example
'user.update.password.update' token payload example
'user.update.password.update' token payload properties
'user.update.password.update' token payload properties
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.create' token payload example
'user.update.username.create' token payload example
'user.update.username.create' token payload properties
'user.update.username.create' token payload properties
user.update.username.delete
This event is triggered when a user’s username is deleted.'user.update.username.delete' token payload example
'user.update.username.delete' token payload example
'user.update.username.delete' token payload properties
'user.update.username.delete' token payload properties
user.update.username.update
This event is triggered when a user’s username is updated.'user.update.username.update' token payload example
'user.update.username.update' token payload example
'user.update.username.update' token payload properties
'user.update.username.update' token payload properties
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.'email.send' token payload example
'email.send' token payload example