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
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.
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.
Example (Javascript)
This example uses express and the jose
package to parse and verify JWTs.
Copy
Ask AI
npm install express jose
The example assumes usage of a single HTTP endpoint for all event types but you could just as well configure
multiple webhooks and use multiple HTTP endpoints.
Copy
Ask AI
// These are the dependencies you should have installed for// this example.const express = require('express');const { createRemoteJWKSet, jwtVerify } = require('jose');const app = express();// Middleware for parsing requests with a JSON payload.app.use(express.json());// Step 1: This defines a POST endpoint at the `/webhook` path.// This path should match the path portion of the URL that you// specified for the callback URL when you created the webhook.// Once you edit a webhook by updating the callback URL of your// webhook, you should change this to match the path portion of// the updated URL for your webhook.app.post('/webhook', async (req, res) => { // Step 2: Extract the event and token from the request body. // You could use the event type to branch and apply // logic/code for specific event types. // This example assumes one endpoint for all event types so // extracting the `event` property may lead to an unused // variable. const { event, token } = req.body; try { // This would likely come from your environment/config. // You can always find your tenant ID on the dashboard // for your project in the Hanko Cloud Console. const tenantId = 'your-tenant-id'; // See also the API reference: // http://docs.hanko.io/api-reference/public/well-known/get-json-web-key-set const jwksUrl = `https://${tenantId}.hanko.io/.well-known/jwks.json`; // Step 3 + 4: Fetch the JWKS of your Hanko tenant, verify // the token signature using the JWKS and extract the // payload. const jwks = createRemoteJWKSet(new URL(jwksUrl)); const { payload } = await jwtVerify(token, jwks); console.log('Decoded token payload:', payload); // Step 6: Do further processing according to your // application's needs. } catch (error) { console.error('Error processing the token:', error.message); } // Your endpoint should respond with a 2XX response within 30 seconds // of receiving a webhook delivery to indicate that the delivery was // successfully received. If your server takes longer than that to // respond, then Hanko terminates the connection and considers the // delivery a failure. res.sendStatus(202);});// Start the Express serverconst PORT = 3000;app.listen(PORT, () => { console.log(`Server is running on http://localhost:${PORT}`);});
Your server must return the complete certificate chain otherwise the request will fail.
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.
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).
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).
The JWT that contains the actual webhook event data. It is a JSON Web Signature (JWS). Webhook recipients
should verify the signature to ensure that the webhook deliveries were sent by Hanko and have not been
tampered with.
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).
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
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
Copy
Ask AI
{ "aud": [ "Test Service ABC" ], "data": { "subject": "Use passcode 325139 to verify your email address", "body_plain": "Enter the following passcode to verify your email address:\n\n325139\n\nThe passcode is valid for 5 minutes.", "to_email_address": "test@example.com", "delivered_by_hanko": false, "language": "en", "type": "passcode", "data": { "service_name": "Test Service ABC", "otp_code": "325139", "ttl": 300, "valid_until": 1737128997 } }, "evt": "email.send", "exp": 1737128997, "iat": 1737128697, "sub": "hanko 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
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.
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.
Example (Javascript)
This example uses express and the jose
package to parse and verify JWTs.
Copy
Ask AI
npm install express jose
The example assumes usage of a single HTTP endpoint for all event types but you could just as well configure
multiple webhooks and use multiple HTTP endpoints.
Copy
Ask AI
// These are the dependencies you should have installed for// this example.const express = require('express');const { createRemoteJWKSet, jwtVerify } = require('jose');const app = express();// Middleware for parsing requests with a JSON payload.app.use(express.json());// Step 1: This defines a POST endpoint at the `/webhook` path.// This path should match the path portion of the URL that you// specified for the callback URL when you created the webhook.// Once you edit a webhook by updating the callback URL of your// webhook, you should change this to match the path portion of// the updated URL for your webhook.app.post('/webhook', async (req, res) => { // Step 2: Extract the event and token from the request body. // You could use the event type to branch and apply // logic/code for specific event types. // This example assumes one endpoint for all event types so // extracting the `event` property may lead to an unused // variable. const { event, token } = req.body; try { // This would likely come from your environment/config. // You can always find your tenant ID on the dashboard // for your project in the Hanko Cloud Console. const tenantId = 'your-tenant-id'; // See also the API reference: // http://docs.hanko.io/api-reference/public/well-known/get-json-web-key-set const jwksUrl = `https://${tenantId}.hanko.io/.well-known/jwks.json`; // Step 3 + 4: Fetch the JWKS of your Hanko tenant, verify // the token signature using the JWKS and extract the // payload. const jwks = createRemoteJWKSet(new URL(jwksUrl)); const { payload } = await jwtVerify(token, jwks); console.log('Decoded token payload:', payload); // Step 6: Do further processing according to your // application's needs. } catch (error) { console.error('Error processing the token:', error.message); } // Your endpoint should respond with a 2XX response within 30 seconds // of receiving a webhook delivery to indicate that the delivery was // successfully received. If your server takes longer than that to // respond, then Hanko terminates the connection and considers the // delivery a failure. res.sendStatus(202);});// Start the Express serverconst PORT = 3000;app.listen(PORT, () => { console.log(`Server is running on http://localhost:${PORT}`);});
Your server must return the complete certificate chain otherwise the request will fail.
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.
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).
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).
The JWT that contains the actual webhook event data. It is a JSON Web Signature (JWS). Webhook recipients
should verify the signature to ensure that the webhook deliveries were sent by Hanko and have not been
tampered with.
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).
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
Indicates whether the credential may be backed up in some fashion such that they may become present
on an authenticator other than their generating authenticator
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
Copy
Ask AI
{ "aud": [ "Test Service ABC" ], "data": { "subject": "Use passcode 325139 to verify your email address", "body_plain": "Enter the following passcode to verify your email address:\n\n325139\n\nThe passcode is valid for 5 minutes.", "to_email_address": "test@example.com", "delivered_by_hanko": false, "language": "en", "type": "passcode", "data": { "service_name": "Test Service ABC", "otp_code": "325139", "ttl": 300, "valid_until": 1737128997 } }, "evt": "email.send", "exp": 1737128997, "iat": 1737128697, "sub": "hanko webhooks"}
