From b62a344e54ff8003157dc48ad1a52e4a92a7a327 Mon Sep 17 00:00:00 2001
From: Dhruwang Jariwala <67850763+Dhruwang@users.noreply.github.com>
Date: Fri, 28 Jul 2023 14:11:21 +0530
Subject: [PATCH] Update Webhook Documentation (#611)

* added webhook payload docs

* ran pnpm format

* update data.id explanation, reformat

---------

Co-authored-by: Matthias Nannt <mail@matthiasnannt.com>
---
 apps/formbricks-com/lib/docsNavigation.ts     |  1 +
 .../webhook-api/webhook-payload/index.mdx     | 69 +++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 apps/formbricks-com/pages/docs/webhook-api/webhook-payload/index.mdx

diff --git a/apps/formbricks-com/lib/docsNavigation.ts b/apps/formbricks-com/lib/docsNavigation.ts
index 604660a71f..e6a4d16f15 100644
--- a/apps/formbricks-com/lib/docsNavigation.ts
+++ b/apps/formbricks-com/lib/docsNavigation.ts
@@ -78,6 +78,7 @@ const navigation = [
       { title: "Get Webhook", href: "/docs/webhook-api/get-webhook" },
       { title: "Create Webhook", href: "/docs/webhook-api/create-webhook" },
       { title: "Delete Webhook", href: "/docs/webhook-api/delete-webhook" },
+      { title: "Webhook Payload", href: "/docs/webhook-api/webhook-payload" },
     ],
   },
   {
diff --git a/apps/formbricks-com/pages/docs/webhook-api/webhook-payload/index.mdx b/apps/formbricks-com/pages/docs/webhook-api/webhook-payload/index.mdx
new file mode 100644
index 0000000000..8203bdbc4a
--- /dev/null
+++ b/apps/formbricks-com/pages/docs/webhook-api/webhook-payload/index.mdx
@@ -0,0 +1,69 @@
+import { Layout } from "@/components/docs/Layout";
+import { Fence } from "@/components/shared/Fence";
+
+export const meta = {
+  title: "Webhook Payload",
+  description: "Learn how to use the Formbricks Webhook API.",
+};
+
+This documentation helps understand the payload structure that will be received when the webhook is triggered in Formbricks.
+
+## An example webhook payload
+
+```
+{
+    "webhookId": "cljwxvjos0003qhnvj2jg4k5i",
+    "event": "responseCreated",
+    "data": {
+        "id": "cljwy2m8r0001qhclco1godnu",
+        "createdAt": "2023-07-10T14:14:17.115Z",
+        "updatedAt": "2023-07-10T14:14:17.115Z",
+        "surveyId": "cljsf3d7a000019cv9apt2t27",
+        "finished": false,
+        "data": {
+            "qumbk3fkr6cky8850bvvq5z1": "Executive"
+        },
+        "meta": {
+            "userAgent": {
+                "os": "Mac OS",
+                "browser": "Chrome"
+            }
+        },
+        "personAttributes": {
+            "email": "test@web.com",
+            "userId": "THIS-IS-A-VERY-LONG-USER-ID-FOR-TESTING"
+        },
+        "person": {
+            "id": "cljold01t0000qh8ewzigzmjk",
+            "attributes": {
+                "email": "test@web.com",
+                "userId": "THIS-IS-A-VERY-LONG-USER-ID-FOR-TESTING"
+            },
+            "createdAt": "2023-07-04T17:56:17.154Z",
+            "updatedAt": "2023-07-04T17:56:17.154Z"
+        },
+        "notes": [],
+        "tags": []
+    }
+}
+
+```
+
+| Variable              | Type    | Description                                                                                                                                    |
+| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| webhookId             | String  | Webhook's Id                                                                                                                                   |
+| event                 | String  | The name of the trigger event [responseCreated, responseUpdated, responseFinished]                                                             |
+| data                  | Object  | Contains the details of the newly created response.                                                                                            |
+| data.id               | String  | Formbricks Response ID.                                                                                                                        |
+| data.createdAt        | String  | The timestamp when the response was created.                                                                                                   |
+| data.updatedAt        | String  | The timestamp when the response was last updated.                                                                                              |
+| data.surveyId         | String  | The identifier of the survey associated with this response.                                                                                    |
+| data.finished         | Boolean | A boolean value indicating whether the survey response is marked as finished.                                                                  |
+| data.data             | Object  | An object containing the response data, where keys are question identifiers, and values are the corresponding answers given by the respondent. |
+| data.meta             | Object  | Additional metadata related to the response, such as the user's operating system and browser information.                                      |
+| data.personAttributes | Object  | An object with attributes related to the respondent, such as their email and a user ID (if available).                                         |
+| data.person           | Object  | Information about the respondent, including their unique id, attributes, and creation/update timestamps.                                       |
+| data.notes            | Array   | An array of notes associated with the response (if any).                                                                                       |
+| data.tags             | Array   | An array of tags assigned to the response (if any).                                                                                            |
+
+export default ({ children }) => <Layout meta={meta}>{children}</Layout>;