Merge pull request #322 from nocodb/docs/webhook-custom-body

docs: webhook custom payload

Author: o1lab

content/docs/automation/webhook/create-webhook.mdx

@@ -115,13 +115,16 @@ For **After Insert** event, you can configure webhook to trigger only when a **s
 
 ### Webhook with custom payload ☁
 
-<Callout type="note">
-    This feature is only available in the paid plans, in both cloud & self-hosted.
-</Callout>
+<Callout type="note">This feature is only available in cloud & self-hosted enterprise plans.</Callout>
 
-In the enterprise edition, you can set up a personalized payload for your webhook. Just head to the `Body` tab to make the necessary configurations. Users can utilize [handlebar syntax](https://handlebarsjs.com/guide/#simple-expressions), which allows you to access and manipulate the data easily.
+Custom payload lets you fully control the body a webhook sends when an event is triggered. You can send the entire event object, a specific field, a compact row summary, or transform rows into arrays/objects that downstream services expect.
+
+NocoDB exposes the current event as `event` inside custom payload. These are processed with [Handlebars-like expressions](https://handlebarsjs.com/guide/#simple-expressions) and a built-in `json` helper ([examples below](#examples)).
+
+#### Example event object
+
+This is the sample event generated by NocoDB after a record is inserted.
 
-Use `{{ json event }}` to access the event data. Sample response is as follows
 ```json
 {
   "type": "records.after.insert",
@@ -144,6 +147,118 @@ Use `{{ json event }}` to access the event data. Sample response is as follows
 }
 ```
 
+In custom payload, you will typically access paths such as `event.data.table_name` or `event.data.rows.[0].Tags`.
+
+#### Adding a custom payload
+
+To add a custom payload, open your webhook in NocoDB's UI and follow these steps:
+1. Click on the **Body** tab
+2. Enter your template using Handlebars expressions and the `json` helper.
+3. Create/update Webhook or use the **Test Webhook** action to verify rendering.
+
+![Webhook custom payload](/img/v2/automations/webhooks/custom-payload.png)
+
+<Callout type="info">Some applications require specific headers to process webhook payloads correctly. For example, if you're sending JSON data, ensure you include the appropriate `Content-Type` header in your webhook configuration (commonly `application/json`).</Callout>
+
+The `json` helper is used to safely serialize values into valid JSON, whether they’re strings, objects, or arrays. It ensures proper quoting and escaping, preventing common errors with quotes, newlines, or special characters. For example, `{{ json event }}` outputs the full event object, while `{{ json event.data.rows.[0].Title }}` safely inserts a single field as a JSON string. This makes it the most reliable way to embed dynamic values in webhook payloads.
+
+Handlebars expressions allow you to dynamically access and manipulate data within templates, similar to how the json helper works for serialization. You can reference fields using dot or bracket notation, iterate over arrays with `{{#each ...}}`, and conditionally include content with `{{#if ...}}`. Learn more about using Handlebars expressions in [Handlebars documentation](https://handlebarsjs.com/guide/#simple-expressions).
+
+#### Examples
+
+Here are some common payload templates you can use as a starting point:
+
+1. **Full event object:**
+Sends the complete event data as JSON
+
+```text
+{
+  "event": {{ json event }}
+}
+```
+
+2. **Single field value:**
+Sends just the `Title` field of the first row
+
+```text
+{
+  "content": {{ json event.data.rows.[0].Title }}
+}
+```
+
+3. **Compact row summary:**
+Sends all fields of the first row as a JSON object
+
+```text
+{
+  "row": {{ json event.data.rows.[0] }}
+}
+```
+
+4. **All rows as array:**
+Sends all rows in the event as a JSON array
+
+```text
+{
+  "rows": {{ json event.data.rows }}
+}
+```
+
+5. **Custom object with metadata:**
+Sends an object with table name, row count, and all rows
+
+```text
+{
+  "table": {{ json event.data.table_name }},
+  "count": {{ json event.data.rows.length }},
+  "rows": {{ json event.data.rows }}
+}
+```
+
+6. **Custom text with field value:**
+Sends a simple message including the `Title` field
+
+```text
+{
+  "message": "New record created with title: {{ event.data.rows.[0].Title }}"
+}
+```
+
+7. **Handlebar logic example:**
+Sends different payloads based on whether rows exist
+
+```text
+{{#if event.data.rows.length}}
+{
+  "hasRows": true,
+  "rows": {{ json event.data.rows }}
+}
+{{else}}
+{
+  "hasRows": false
+}
+{{/if}}
+```
+
+8. **Multiple rows with formatting:**
+Sends all rows with only `Id` and `Title`, formatted as a JSON array
+
+```text
+{
+  "records": [
+    {{#each event.data.rows}}
+      {{#if @first}}{{else}},{{/if}}
+      {
+        "Id": {{ Id }},
+        "Title": {{ json Title }}
+      }
+    {{/each}}
+  ]
+}
+```
+
+---
+
 
 ### Webhook response sample