From 99af579675746d6dd24587600961914077000d77 Mon Sep 17 00:00:00 2001
From: Raju Udava <86527202+dstala@users.noreply.github.com>
Date: Tue, 22 Feb 2022 14:31:53 +0530
Subject: [PATCH] chore: webhook documentation update
Signed-off-by: Raju Udava <86527202+dstala@users.noreply.github.com>
---
.../en/developer-resources/webhooks.md | 181 +++++++++++++++---
1 file changed, 154 insertions(+), 27 deletions(-)
diff --git a/packages/noco-docs/content/en/developer-resources/webhooks.md b/packages/noco-docs/content/en/developer-resources/webhooks.md
index 7c08bb1c4d..170d274b8c 100644
--- a/packages/noco-docs/content/en/developer-resources/webhooks.md
+++ b/packages/noco-docs/content/en/developer-resources/webhooks.md
@@ -1,44 +1,171 @@
---
-title: 'Webhooks'
-description: 'Webhooks'
+title: "Webhooks"
+description: "Webhooks"
position: 1030
-category: 'Developer Resources'
-menuTitle: 'Webhooks'
+category: "Developer Resources"
+menuTitle: "Webhooks"
---
+## Triggers
-## Triggers available
Webhooks allows user to trigger on certain operations on following database operations
-- AFTER INSERT
-- AFTER UPDATE
-- AFTER DELETE
+
+- AFTER INSERT
+- AFTER UPDATE
+- AFTER DELETE
The triggers will trigger asynchronously without blocking the actual operation.
-## Trigger to following applications/services
+### Applications/services
-| Trigger | Details |
-|-------|-------|
-|Email| Send email to certain email addresses |
-|Slack| Notify via Slack channel |
-|Microsoft Teams| Notify via Microsoft Teams channel |
-|Discord| Notify via Discord channel|
-|Mattermost| Notify via Mattermost channel|
-|Twilio| Send SMS to certain mobile numbers |
-|Whatsapp Twilio| Send Whatsapp messages to numbers using Twilio |
-|URL| Invoke an HTTP API |
+| Trigger | Details |
+| --------------- | ---------------------------------------------- |
+| Email | Send email to certain email addresses |
+| Slack | Notify via Slack channel |
+| Microsoft Teams | Notify via Microsoft Teams channel |
+| Discord | Notify via Discord channel |
+| Mattermost | Notify via Mattermost channel |
+| Twilio | Send SMS to certain mobile numbers |
+| Whatsapp Twilio | Send Whatsapp messages to numbers using Twilio |
+| URL | Invoke an HTTP API |
-## Accessing Data
+
+## Accessing Data: Handlebars
-The current row data and other details will be available in the hooks payload so the user can use [handlebar syntax](https://handlebarsjs.com/guide/#simple-expressions) to use data.
+The current row data and other details will be available in the hooks payload so the user can use [handlebar syntax](https://handlebarsjs.com/guide/#simple-expressions) to use data.
> We are using [Handlebars](https://handlebarsjs.com/) library to parse the payload internally.
-### Available values in context
+### Example
+
+For a table with column names (id, title, created_at, updated_at).
+For INSERT/ UPDATE based triggers, use following handlebars to access corresponding **data** fields.
+
+- {{ **data**.id }}
+- {{ **data**.title }}
+- {{ **data**.created_at }}
+- {{ **data**.updated_at }}
+
+Note that, for Update trigger - all the fields in the ROW will be accessible, not just the field updated.
+For DELETE based triggers, **only** {{ data.id }} is accessible representing ID of the column deleted.
+
+For all trigger, following **user** information associated with person trigger can be accessed.
+
+- {{ **user**.id }} : Unique auto incremented NocoDB system value
+- {{ **user**.email }} : User E-mail.
+- {{ **user**.roles }} : User Role amongst [Owner, Creator, Editor, Commenter, Viewer].
+
+### JSON format
+
+Use {{ json data }} {{ json user }} to dump complete data & user information available in JSON format
+
+### Additional references:
+
+[Handlebar Guide](https://handlebarsjs.com/guide/).
+
+# Application Guide
+
+## Discord
+
+### 1. Create WebHook
+
+- On Discord, open your Server Settings and head into the Integrations tab:
+- Click the "Create Webhook" button to create a new webhook!
+
+
+
+- Choose channel to which this webhook will post to.
+- Copy webhook URL
+
+
+
+(Sample webhook URL: https://discord.com/api/webhooks/945558283756908644/GNUtiGuzfOky6wZ4ce30XuXc1sbPK3Od7EC-4t6hihh5Fovv6oU9OsdT6mGuoL1QlTzj).
+Detailed procedure for discord webhook described [here](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks).
+
+### 2. Install Plugin
+
+- Open 'App Store' (under Settings), hover over Discord tile. Click 'Install'.
+
+
+
+- Provide a name of your choice (not to be confused with Discord Channel name).
+- Paste Discord Webhook URL copied from Step (1.) above.
+
+
+
+### 3. Configure
+
+- Open project, associated table.
+- Click 'More' > 'Webhooks'.
+
+
+
+- Click 'Add New Webhook'
+
+
+
+- Configure
+ - **Title**: Name of your choice to identify this Webhook.
+ - **Event**: Trigger event. Choose between.
+ - After Insert: Trigger event for new ROW insertion.
+ - After Update: Trigger event for existing ROW updation.
+ - After Delete: Trigger event for ROW deletion
+ - **On Condition**: [Optional] Enable if you wish to associate additional condition/constraint with the trigger configured above.
+ - **Notification**: Select 'Discord'.
+ - **Select Discord Channels**: Select from the drop down list, channel name configured in Step (2). Please click on 'Reload' if drop down list is empty.
+ - **Body**: Message to be posted over Discord channel, via webhooks on trigger of configured event.
+ - Body can contain plain text &
+ - Handlebars {{ }}
+
+
+## Microsoft Teams
+### 1. Create WebHook
+
+- On Teams, open your channel, click on three-dots menu (far right) and select 'Connectors'
+
+
+
+
+- Select incoming webhook & click 'Configure'
+
+
+
+- Create webhook, Copy webhook URL
+
+
+
+
+### 2. Install Plugin
+
+- Open 'App Store' (under Settings), hover over 'Microsoft Teams' tile. Click 'Install'.
+
+
+
+- Provide a name of your choice (not to be confused with Teams Channel name).
+- Paste MS Teams Webhook URL copied from Step (1.) above.
+
+
+
+### 3. Configure
+
+- Open project, associated table.
+- Click 'More' > 'Webhooks'.
+
+
+
+- Click 'Add New Webhook'
-| Name | Details | Example|
-|-------|-------|-------|
-| **data** | Contains row data | `{{ data.Title }}` |
-| **user** | Logginned user object | `{{ user.id }}` |
-| **env** | Environment values | `{{ env.SITE_URL }}` |
+
+- Configure
+ - **Title**: Name of your choice to identify this Webhook.
+ - **Event**: Trigger event. Choose between.
+ - After Insert: Trigger event for new ROW insertion.
+ - After Update: Trigger event for existing ROW updation.
+ - After Delete: Trigger event for ROW deletion
+ - **On Condition**: [Optional] Enable if you wish to associate additional condition/constraint with the trigger configured above.
+ - **Notification**: Select 'Microsoft Teams'.
+ - **Select Discord Channels**: Select from the drop down list, channel name configured in Step (2). Please click on 'Reload' if drop down list is empty.
+ - **Body**: Message to be posted over Teams channel, via webhooks on trigger of configured event.
+ - Body can contain plain text &
+ - Handlebars {{ }}