chore(docs): add webhook docs (#1346)

* extend config doc with webhook configuration * add chapter for webhooks to backend docs Co-authored-by: Stefan Jacobi <[email protected]>
teamhanko · Feb 16, 2024 · 8500b19 · 8500b19
1 parent e604679
commit 8500b19
Show file tree

Hide file tree

Showing 2 changed files with 105 additions and 1 deletion.
diff --git 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: <YOUR WEBHOOK ENDPOINT>
+      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
@@ -861,7 +861,77 @@ saml:
         phone: "<PHONE_ATTRIBUTE_IN_IDP_ASSERTION>"
         ##
         #
-        # E-Phone Verified - attribute of the user
+        # Phone Verified - attribute of the user
         #
         phone_verified: "<PHONE_VERIFIED_ATTRIBUTE_IN_IDP_ASSERTION>"
+##
+#
+# 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: "<YOUR WEBHOOK ENDPOINT URL>"
+      ##
+      #
+      # 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
 ```