diff --git a/.claude/skills/documentation/SKILL.md b/.claude/skills/documentation/SKILL.md
index 479e32a6a..8ba2efa37 100644
--- a/.claude/skills/documentation/SKILL.md
+++ b/.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 |
diff --git a/.claude/skills/documentation/workflow.md b/.claude/skills/documentation/workflow.md
index ec1c876d5..c49d4d9b0 100644
--- a/.claude/skills/documentation/workflow.md
+++ b/.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
diff --git a/docs/4. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md b/docs/4. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
index 935801d14..80a74d5de 100644
--- a/docs/4. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
+++ b/docs/4. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
@@ -1,17 +1,17 @@
-
| 3 minutes read |
Level: Advanced |
- Last Updated: March 2026 |
+ Last Updated: June 2026 |
**Webhook calls are used to communicate with third-party applications within flows. They allow NGOs to receive and handle incoming messages, delivery receipts and other events from WhatsApp in a seamless and automated manner.**
-___
+---
+
## Using Webhooks in Glific
Please have a look at the steps to call Webhooks in Glific.
@@ -21,11 +21,11 @@ Please have a look at the steps to call Webhooks in Glific.
2. Call Webhook in a node.
- 1. Choose to `Call a webhook` in the dropdown in node action.
- 1. Choose `POST` in response type.
- 1. Enter the `URL` where you want a Webhook connection.
- 1. Click on the `Post Body` tab.
- 1. Enter the variables which you want to pass through the webhook.
+ 1. Choose to `Call a webhook` in the dropdown in node action.
+ 1. Choose `POST` in response type.
+ 1. Enter the `URL` where you want a Webhook connection.
+ 1. Click on the `Post Body` tab.
+ 1. Enter the variables which you want to pass through the webhook.
```
{
@@ -38,22 +38,18 @@ Please have a look at the steps to call Webhooks in Glific.
-
-
3. Click `OK` to save the changes
+---
-___
# Use webhook response in the flows
-1. Let's say you make a webhook call (by using the above steps) and you want to use the response variable in the flow.
+1. Let's say you make a webhook call (by using the above steps) and you want to use the response variable in the flow.
-
-
For example, if you send a response like a below object
```
@@ -63,17 +59,71 @@ 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**
+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**
+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
-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.
+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.
+- **Nesting is limited to 5 parts in a path.** Glific keeps the full shape of your JSON — objects inside objects, arrays inside objects — but it can only read a path that is up to **five dot-separated parts** long. Counting `@results` and your webhook name, that leaves room to go **3 levels deep inside your response** (for example `@results.mywebhook.user.address.city`). Anything deeper is not read, so keep the values you need within that depth.
+
+## 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:
+
+- **A path can be at most 5 parts long.** `@results.mywebhook.user.address.city` is the deepest you can read (that is 3 levels into your response). A value buried deeper — `@results.mywebhook.a.b.c.d` — will not be read. If your data is deeper than that, flatten it in your API before returning it.
+- **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
Once the webhook setup is complete. You can test it by executing the flow in Glific. There may a case, the webhook is not set up correctly and there are some errors in Webhook calls.
@@ -84,17 +134,16 @@ Glific has **Webhook Logs** from where you can check the status of a Webhook cal
-
1. Webhook logs page will show the results of your webhook calls with the below details
- 1. `Time` - Time of the webhook call.
- 1. `URL` - The URL which is used in webhook call.
- 1. `Status` - Success / Error
- 1. `Status Code`- Status code returned from the webhook call.
- 1. `Error` - Error is an error returned. NULL in the case of success
- 1. `Method` - GET / POST
- 1. `Request Header` - Request header of the webhook call
- 1. `Request JSON` - JSON of the webhook call
- 1. `Response JSON` - JSON response received from the webhook call.
+ 1. `Time` - Time of the webhook call.
+ 1. `URL` - The URL which is used in webhook call.
+ 1. `Status` - Success / Error
+ 1. `Status Code`- Status code returned from the webhook call.
+ 1. `Error` - Error is an error returned. NULL in the case of success
+ 1. `Method` - GET / POST
+ 1. `Request Header` - Request header of the webhook call
+ 1. `Request JSON` - JSON of the webhook call
+ 1. `Response JSON` - JSON response received from the webhook call.
@@ -105,7 +154,8 @@ Glific has **Webhook Logs** from where you can check the status of a Webhook cal
1. `View` will open up the response received in a pop-up window. You can check or copy the text to know more details of the response.
-___
+
+---
## Reference Article