docs: enhance webhook documentation with response structure details a…

.claude/skills/documentation/SKILL.md

@@ -37,6 +37,17 @@ The Glific frontend lives at `../glific-frontend/` relative to this repo.
 | `../glific-frontend/src/routes/AuthenticatedRoute/AuthenticatedRoute.tsx` | All route paths (maps feature name → URL) |
 | `../glific-frontend/src/graphql/queries/` | GraphQL queries (understand data a feature displays) |
 
+### Backend code location
+
+The Glific backend (Elixir/Phoenix, repo `glific/glific`) lives at `../glific/` relative to this repo. Read it only to confirm **user-observable behavior** the frontend doesn't make obvious — defaults, validation rules, limits, what a setting actually does, why an action is blocked. Do **not** document internal architecture (see the anti-patterns in `style-writing.md`).
+
+| Path | What it contains |
+|------|-----------------|
+| `../glific/lib/glific/{feature}/` | Domain logic for a feature — defaults, validations, business rules |
+| `../glific/lib/glific/{feature}.ex` | The feature's public context module (entry-point functions) |
+| `../glific/lib/glific_web/resolvers/{feature}.ex` | GraphQL resolvers — what each query/mutation actually does |
+| `../glific/lib/glific_web/schema/{feature}_types.ex` | GraphQL types, fields, and args exposed for the feature |
+
 ## File index
 
 | File | Purpose |

.claude/skills/documentation/workflow.md

@@ -23,12 +23,14 @@ Read what's needed for the task:
 3. Read `../glific-frontend/src/routes/AuthenticatedRoute/AuthenticatedRoute.tsx` to find the URL route
 4. Check existing docs in `docs/` for the feature (search for the feature name in file names and content)
 5. Optionally read `../glific-frontend/src/graphql/queries/{Feature}.ts` to understand what data the feature displays
+6. If user-observable behavior is unclear from the UI alone (defaults, validation rules, limits, why an action is blocked/allowed), read the backend: `../glific/lib/glific/{feature}/` and `../glific/lib/glific/{feature}.ex` for domain logic, `../glific/lib/glific_web/resolvers/{feature}.ex` and `../glific/lib/glific_web/schema/{feature}_types.ex` for what each query/mutation exposes. Translate findings into plain user-facing language — never document internal architecture.
 
 **Mode B — PR Number:**
 1. `gh pr diff #PR_NUMBER --repo glific/glific-frontend` to see what changed
 2. Identify affected containers from the changed file paths
 3. Read the changed files in full to understand new behavior
 4. Check existing docs for the affected area
+5. If the PR is in the backend repo (`glific/glific`) or the frontend change depends on backend behavior, run `gh pr diff #PR_NUMBER --repo glific/glific` and/or read the relevant `../glific/lib/...` files (see the backend paths above) to understand the user-observable change
 
 ## 4. Determine Placement
 

docs/4. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md

@@ -63,7 +63,7 @@ For example, if you send a response like a below object
 }
 ```
 
-> Please note that your webhook should always return a JSON object (not an array). 
+> Your webhook should return JSON. A JSON object is the simplest to work with, but arrays are also supported — see [How the response should be structured](#how-the-response-should-be-structured) below.
 
 Then you can use that response as **@results.mywebhook.success_message** Or if you want to use any other variable then it will be **@results.mywebhook.*YOUR_RESPONSE_OBJECT_KEY**
 
@@ -73,6 +73,60 @@ Then you can use that response as **@results.mywebhook.success_message** Or if y
 
 Here my webhook is a custom name you defined on your webhook node and **success_message**  is the key of the response object you send back in a webhook call.
 
+## How the response should be structured
+
+When your external API replies to a webhook call, Glific reads the **JSON body** of the response and saves it under your webhook's result name. A few rules decide what you can read back:
+
+- **Return JSON.** Glific only parses JSON response bodies. If the body is not valid JSON, nothing is saved to the result and the call is logged as an error.
+- **A JSON object is the cleanest choice.** Every key in the object becomes a value you can read with **@results.YOUR_WEBHOOK_NAME.KEY**.
+- **Arrays are supported too.** If your API returns a JSON array, Glific turns it into numbered keys starting at `0` — the first item is `0`, the second is `1`, and so on. You then read an item by its number.
+- **There is no fixed nesting limit.** Glific keeps the full shape of your JSON — objects inside objects, arrays inside objects — so you can reach any value by following its path.
+
+## Accessing nested values
+
+You reach a value by writing its path after the webhook name, separating each level with a dot:
+
+**@results.YOUR_WEBHOOK_NAME.LEVEL1.LEVEL2...**
+
+Say your webhook is named **mywebhook** and your API returns this:
+
+```json
+{
+  "status": "success",
+  "user": {
+    "name": "Anita",
+    "address": {
+      "city": "Mumbai",
+      "pincode": "400001"
+    }
+  },
+  "courses": [
+    { "title": "Maths", "score": 88 },
+    { "title": "Science", "score": 92 }
+  ]
+}
+```
+
+Here is how to read each value:
+
+| You want | Use this |
+|---|---|
+| The status | `@results.mywebhook.status` |
+| The user's name | `@results.mywebhook.user.name` |
+| The user's city (object inside an object) | `@results.mywebhook.user.address.city` |
+| The first course title (array → item `0`) | `@results.mywebhook.courses.0.title` |
+| The second course's score | `@results.mywebhook.courses.1.score` |
+
+A few things to keep in mind:
+
+- **Array items are numbered from `0`.** The first item is always `0`, not `1`.
+- **Match the keys exactly**, including upper- and lower-case. `@results.mywebhook.User.name` will not find `user`.
+- **Check a value exists before you use it.** If a key is missing from the response, its path returns nothing. Use a **Wait for result** or a split node to branch on whether the value came back.
+
+:::note
+Want to confirm the exact shape your API returned? Open **Webhook Logs** (below) and view the **Response JSON** for that call. Copy the key names straight from there to build your paths.
+:::
+
 ___
 ## Checking Webhook Logs