From 452261808211cadde0a0666a5829d5c09fd07962 Mon Sep 17 00:00:00 2001 From: Stefan Jacobi Date: Thu, 15 Feb 2024 17:14:25 +0100 Subject: [PATCH] chore(docs): add webhook docs * extend config doc with webhook configuration * add chapter for webhooks to backend docs --- backend/README.md | 34 ++++++++++++++++++++ backend/docs/Config.md | 72 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 105 insertions(+), 1 deletion(-) diff --git a/backend/README.md b/backend/README.md index 280c022cb..86cf332a9 100644 --- a/backend/README.md +++ b/backend/README.md @@ -19,6 +19,7 @@ easily integrated into any web app with as little as two lines of code. - [Rate Limiting](#rate-limiting) - [Social logins](#social-logins) - [User import](#user-import) + - [Webhooks](#webhooks) - [API specification](#api-specification) - [Configuration reference](#configuration-reference) - [License](#license) @@ -489,6 +490,39 @@ To import users run: > hanko user import -i ./path/to/import_file.json +### Webhooks + +#### Events +Webhooks are an easy way to get informed about changes in your Hanko instance (e.g. user or email updates). +Hanko provides the following event structure: + +| Event | Triggers on | +|---------------------------|----------------------------------------------------------------------------------------------------| +| user | user creation, user deletion, user update, email creation, email deletion, change of primary email | +| user.create | user creation | +| user.delete | user deletion | +| user.update | user update, email creation, email deletion, change of primary email | +| user.update.email | email creation, email deletion, change of primary email | +| user.update.email.create | email creation | +| user.update.email.delete | email deletion | +| user.update.email.primary | change of primary email | + +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. + +#### Enabling Webhooks + +You can activate webhooks by adding the following snippet to your configuration file: + +```yaml +webhooks: + enabled: true + hooks: + - callback: + events: + - user +``` + ## API specification - [Hanko Public API](https://docs.hanko.io/api/public) diff --git a/backend/docs/Config.md b/backend/docs/Config.md index fe6010cd7..75870c64d 100644 --- a/backend/docs/Config.md +++ b/backend/docs/Config.md @@ -861,7 +861,77 @@ saml: phone: "" ## # - # E-Phone Verified - attribute of the user + # Phone Verified - attribute of the user # phone_verified: "" +## +# +# Webhook Config Section +# +webhooks: + ## + # + # Enabled - Enables the webhook feature + # + enabled: false + ## + # + # Allow timely expiration - Toggle for disabling webhooks when unused for 30 days (only for database webhooks) + # + allow_time_expiration: false + ## + # + # Hooks - List of webhooks to inform when a change occurs + # + hooks: + ## + # + # Callback - Endpoint URL to which the change data will be sent + # + - callback: "" + ## + # + # Events - Webhook events to listen for + # + events: + ## + # + # User - Triggers on: user creation, user deletion, user update, email creation, email deletion, change of primary email + # + - user + ## + # + # User Creation - Triggers on: user creation + # + - user.create + ## + # + # User Deletion - Triggers on: user deletion + # + - user.delete + ## + # + # User Update - Triggers on: user update, email creation, email deletion, change of primary email + # + - user.update + ## + # + # Email - Triggers on: email creation, email deletion, change of primary email + # + - user.update.email + ## + # + # Email - Triggers on: email creation + # + - user.update.email.create + ## + # + # Email - Triggers on: email deletion + # + - user.update.email.delete + ## + # + # Email - Triggers on: change of primary email + # + - user.update.email.primary ```