Webhooks

Learn more about Webhooks

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.

Example (Javascript)

This example uses express and the jose package to parse and verify JWTs.

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.

// 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 server
const 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.

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 payload example

user.create

{
    "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
    "event": "user.create"
}

Event payload properties

token · string

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.

event · string

The event that triggered this webhook

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.create' token payload example

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.create' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

user.delete

This event is triggered when a user is deleted.

'user.delete' token payload example

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.delete' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

user.login

This event is triggered when a user logs in.

'user.login' token payload example

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.login' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

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

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.update.email.create' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

user.update.email.delete

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

'user.update.email.delete' token payload example

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.update.email.delete' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

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

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.update.email.primary' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

user.update.password.update

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

'user.update.password.update' token payload example

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.update.password.update' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

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

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.update.username.create' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

user.update.username.delete

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

'user.update.username.delete' token payload example

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.update.username.delete' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

user.update.username.update

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

'user.update.username.update' token payload example

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "created_at": "2025-01-15T12:57:56.724052Z",
        "emails": [
            {
                "id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "address": "[e-mail]",
                "is_verified": true,
                "is_primary": true,
                "created_at": "2025-01-15T13:57:56.72784Z",
                "updated_at": "2025-01-15T13:57:56.72801Z"
            }
        ],
        "id": "42fbd0dc-28fb-4144-892c-c2c4a0f8f5d8",
        "identities": [
            {
                "id": "b3af92c5-414c-4c6b-a3ea-82ee263badef",
                "provider_id": "123456abcd",
                "provider_name": "testprovider",
                "email_id": "d31be36d-08d7-409f-8437-1920628e6e51",
                "created_at": "2025-01-17T13:40:11Z",
                "updated_at": "2025-01-17T13:40:13Z"
            }
        ],
        "ip_address": "127.0.0.1",
        "otp": {
            "id": "a7efd1ee-d7b2-440e-9284-625e06931745",
            "created_at": "2025-01-17T13:39:29.081428Z"
        },
        "password": {
            "id": "6ec87b0c-67db-42ef-9adb-d106734bde02",
            "created_at": "2025-01-15T13:57:56.735651Z",
            "updated_at": "2025-01-15T13:57:56.735651Z"
        },
        "updated_at": "2025-01-15T13:57:56.724255Z",
        "username": {
            "id": "61580d7d-0c11-4c25-bfca-ace21a14cc01",
            "username": "testmakker",
            "created_at": "2025-01-15T14:45:00.293001Z",
            "updated_at": "2025-01-17T13:46:41.700373Z"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
        "webauthn_credentials": [
            {
                "id": "eaYxbrFQJjl5dW5SAr0KznEmHwAen8HUAiaKN9ijsDY",
                "public_key": "pQECAyYgASFYIMq-SVnCDGIJjK2TAJyEQyXNtOw7x_MuEVUQuW80-AOcIlggyEcR_v5C8PuhrThwgx2urmRqviIb7dyXmGr3oyWk2rU",
                "attestation_type": "packed",
                "aaguid": "70a4ab68-d027-451a-9c86-3b8fd8414f68",
                "last_used_at": "2025-01-17T12:38:28.698563Z",
                "created_at": "2025-01-17T12:38:28.698563Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": true
            },
            {
                "id": "BPtYkS1prrGu1owU3StJwWM5uYtVoD1-h4N_rPHrB84",
                "public_key": "pQECAyYgASFYILo4i3yC0V2kciBHL96EOx08h32CXXIFnuUmggHOhkGvIlggQFIp4CeJhzGpCiTNuQQoyiKV7oMLYxM549ctLJXJkZ0",
                "attestation_type": "packed",
                "aaguid": "649b9062-5892-4223-832b-921c5bce5827",
                "last_used_at": "2025-01-17T12:39:06.718171Z",
                "created_at": "2025-01-17T12:39:06.718171Z",
                "transports": [
                    "usb"
                ],
                "backup_eligible": false,
                "backup_state": false,
                "mfa_only": false
            }
        ]
    },
    "evt": "<string>", // the corresponding event type
    "exp": 1737118303,
    "iat": 1737118003,
    "sub": "hanko webhooks"
}

'user.update.username.update' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

id · string

The ID of the user

created_at · string

Time of creation of the user

emails · object[]

Show child attributes

id · string

The ID of the email

address · string

The actual email address

created_at · string

Time of creation of the email

is_primary · boolean

Indicates whether this is the primary email

is_verified · boolean

Indicates whether this email is verified

updated_at · string

Time of last update of the email

identities · object[]

Show child attributes

id · string

The ID of the identity

provider_id · string

The ID of the user at the third party provider

provider_name · string

The name of the third party provider

email_id · string

The ID of the email the identity is related to

created_at · string

Time of creation of the identity

updated_at · string

Time of last update of the identity

otp · object

MFA OTP credential of the user

Show child attributes

id · string

ID of the OTP credential

created_at · string

Time of creation of the OTP credential

password · object

Representation of the password credential of the user

Show child attributes

id · string

The ID of the password credential

created_at · string

Time of creation of the password credential

updated_at · string

Time of last update of the password credential

updated_at · string

Time of last update of the user

username · object

The username of the user

Show child attributes

id · string

The ID of the username

username · string

The actual username of the user

created_at · string

Time of creation of the username

updated_at · string

Time of last update of the username

webauthn_credentials · object

Registered WebAuthn credentials (passkeys and security keys) of the user

Show child attributes

aaguid · string

The ID authenticator that created the credential

attestation_type · string

Format in which the signature is represented and the various contextual bindings are incorporated into the attestation statement by the authenticator

backup_eligible · string

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

backup_state · string

Indicates whether this credential is backed up or not

created_at · string

The time of creation of the credential

id · string

The ID of the credential

last_used_at · string

Indicates when the credential was lst used

public_key · string

The public key of the credential (Base64URL string)

transports · string[]

Communication methods/protocols used to create the credential

mfa_only · string

Indicates whether this is an MFA credential (security key) or a first factor credential (passkey)

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"

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

{
    "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": "[e-mail]",
        "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"
}

'email.send' token payload properties

aud · string[]

The recipients the token is intended for

data · object

Show child attributes

subject · string

The subject line of the email

body_plain · string

The plain text version of the email body

body · string

The HTML version of the email body (nullable)

to_email_address · string

The recipient’s email address

delivered_by_hanko · boolean

Indicates whether the email was delivered by Hanko (true) or not (false).

accept_laguage · boolean

Deprecated, rely on language instead.

The preferred language for the email content.

language · string

The preferred language for the email content.

type · enum<string>

The type of the email being sent.

Available options: login, email_login_attempted, email_registration_attempted, email_verification, recovery

data · object

Additional data.

Show child attributes

service_name · string

The name of the service set in the console as the project name

otp_code · string

The passcode the user can use to log in

ttl · number

The validity duration of the passcode in seconds

valid_until · number

The Unix timestamp indicating when the passcode expires

evt · string

The event that triggered the webhook containing this data

exp · number

The expiration date of the token

iat · number

The time at which the token was issued

sub · string · default: "hanko webhooks"