Webhooks are an easy way to get informed about changes in your Hanko instance (e.g. user or email updates). To use webhooks you have to provide an endpoint on your application which can process the events. Please be aware that your endpoint need to respond with an HTTP status code 200. Else-wise the delivery of the event will not be counted as successful.

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

​
Events

When a webhook is triggered it will send you a JSON body which contains the event and a jwt. The JWT contains 2 custom claims:

  • data: contains the whole object for which the change was made. (e.g.: the whole user object when an email or user is changed/created/deleted)
  • evt: the event for which the webhook was triggered

A typical webhook event looks like:

{
  "token": "the-jwt-token-which-contains-the-data",
  "event": "name of the event"
}

​
Event Types

Hanko sends webhooks for the following event types:

EventTriggers on
useruser creation, user deletion, user update, email creation, email deletion, change of primary email
user.createuser creation
user.deleteuser deletion
user.updateuser update, email creation, email deletion, change of primary email
user.update.emailemail creation, email deletion, change of primary email
user.update.email.createemail creation
user.update.email.deleteemail deletion
user.update.email.primarychange of primary email
email.sendan email was send

As you can see, events can have subevents. You are able to filter which events you want to receive by either selecting a parent event when you want to receive all subevents or selecting specific subevents.

​
Restrictions

Due to security concerns there are some usage restrictions for webhooks in place:

  • A webhook will be disabled after 30 days without usage. In this scenario usage describes the successful triggering of events

    This mechanism can be disabled by setting webhooks.allow_time_expiration to false

  • A webhook will also be disabled when our trigger mechanism is not successful. The mechanism will try 5 attempts of sending events before disabling a webhook. A trigger is unsuccessful when:

    • your callback URL is not reachable due to network errors or a wrong url
    • your webhook endpoint returns HTTP Status codes >= 400

The restrictions are not available for webhooks defined in the config file.

​
Data

When a webhook is triggered it will send you a JSON body which contains the event and a jwt. The JWT contains 2 custom claims:

  • data: contains the whole object for which the change was made. (e.g.: the whole user object when an email or user is changed/created/deleted)
  • evt: the event for which the webhook was triggered

Was this page helpful?

SessionsCustom Emails