docs: enhance webhook documentation with response structure details a…#635
docs: enhance webhook documentation with response structure details a…#635priyanshu6238 wants to merge 4 commits into
Conversation
📝 WalkthroughWalkthroughThe PR updates documentation guidance for researching backend behavior, including when to inspect backend code and how to describe findings. It also updates webhook documentation to allow JSON objects and arrays in responses, explain how response data is stored, and document nested value access syntax and lookup rules. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 markdownlint-cli2 (0.22.1)docs/4. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.mdmarkdownlint-cli2 wrapper config was not available before execution Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
🚀 Deployed on https://deploy-preview-635--glific-docs.netlify.app |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md:
- Around line 76-84: Clarify the invalid-JSON behavior in the webhook response
section so flow authors know what happens after a parse failure. Update the “How
the response should be structured” guidance to state whether the webhook step in
the Call a webhook flow action still completes with an empty result or instead
errors/stops execution, and make that behavior explicit near the JSON parsing
rules in this document.
- Around line 126-128: The note in the Webhook documentation uses a relative
“below” reference that may not resolve reliably in rendered output; update the
text in the note near the Webhook Logs mention to either match the actual
section placement under the “Checking Webhook Logs” heading or replace “below”
with a direct anchor link to the Webhook Logs section. Use the existing note
block and the “Checking Webhook Logs”/“Webhook Logs” headings as the locating
symbols.
- Around line 122-125: The guidance for handling missing values uses the wrong
node name, so update the prose in the webhook flow docs to reference the exact
Glific UI label. In the section discussing checking whether a value exists
before use, replace the generic “split node” wording with “Split by a result in
the flow” and keep “Wait for result” unchanged so the branching instruction
matches the actual workflow node names.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 302a92b5-bf30-48d2-a303-d95f09596606
📒 Files selected for processing (3)
.claude/skills/documentation/SKILL.md.claude/skills/documentation/workflow.mddocs/4. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
| ## 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. | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win
Clarify what "nothing is saved" means for flow authors.
Line 80 states that invalid JSON means "nothing is saved to the result and the call is logged as an error." Consider clarifying whether the flow can still continue (with an empty result) or if the webhook node itself errors and stops flow execution. This distinction matters for authors designing error-handling paths.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
around lines 76 - 84, Clarify the invalid-JSON behavior in the webhook response
section so flow authors know what happens after a parse failure. Update the “How
the response should be structured” guidance to state whether the webhook step in
the Call a webhook flow action still completes with an empty result or instead
errors/stops execution, and make that behavior explicit near the JSON parsing
rules in this document.
| - **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. | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify exact node type names in Glific documentation or codebase
rg -n "Wait for result" docs/
rg -n "split node" docs/
rg -n "Split by" docs/ --type mdRepository: glific/docs
Length of output: 9250
Update the specific node name for handling missing values.
While "Wait for result" is the correct node name, "split node" is too generic and does not match the Glific UI. The precise node for branching based on workflow results is Split by a result in the flow.
Replace "split node" with "Split by a result in the flow" in the guidance:
Use a Wait for result or a Split by a result in the flow node to branch on whether the value came back.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
around lines 122 - 125, The guidance for handling missing values uses the wrong
node name, so update the prose in the webhook flow docs to reference the exact
Glific UI label. In the section discussing checking whether a value exists
before use, replace the generic “split node” wording with “Split by a result in
the flow” and keep “Wait for result” unchanged so the branching instruction
matches the actual workflow node names.
|
It doesn't look good to me, so I'm closing this for now. |
There was a problem hiding this comment.
Actionable comments posted: 5
♻️ Duplicate comments (2)
docs/4. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md (2)
119-119: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winUse the precise Glific node name.
"split node" is too generic and does not match the Glific UI. The precise node for branching on workflow results is "Split by a result in the flow". Update:
Use a Wait for result or a Split by a result in the flow node to branch on whether the value came back.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md at line 119, The branching guidance in this section uses a generic node name that does not match the Glific UI. Update the wording in the webhook flow action docs to use the exact node name “Split by a result in the flow” alongside “Wait for result,” so the sentence in this section references the correct workflow node name consistently.
74-74: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winClarify what happens after invalid JSON.
The text states "nothing is saved to the result and the call is logged as an error" but does not clarify whether the flow step completes with an empty result (allowing the flow to continue) or whether the webhook node itself errors and stops execution. This distinction matters for authors designing error-handling paths.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md around lines 74, Clarify the invalid-JSON behavior in the webhook response section so flow authors know what happens after a parse failure. Update the “How the response should be structured” guidance to state whether the webhook step in the Call a webhook flow action still completes with an empty result or instead errors/stops execution, and make that behavior explicit near the JSON parsing rules in this document.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md at line 74, Clarify the invalid-JSON behavior in the webhook response guidance so authors know whether the Call a webhook step completes with an empty result or errors and stops execution. Update the “How the response should be structured” section near the JSON parsing rule for the webhook action, making the outcome explicit for invalid JSON and keeping the wording aligned with the existing “Return JSON” note.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md:
- Around line 24-28: The “Call a webhook” flow text uses the wrong term for the
dropdown selection; update the step in the webhook docs to refer to the HTTP
method instead of “response type.” In the “Call a webhook” section, revise the
instruction around the POST selection so it clearly says to choose POST as the
HTTP method, matching the dropdown behavior and terminology used elsewhere in
the flow actions docs.
- Line 11: The current webhook description in the flow action docs mixes inbound
WhatsApp handling with the outbound behavior of Call a webhook. Update the
description in the webhook flow action documentation to clearly state that this
action sends data from a flow to an external API and can use the response in
later steps, using the “Call a webhook” terminology to avoid confusion with
WhatsApp message reception.
- Around line 137-146: The webhook logs field list has inconsistent formatting
and awkward wording in the “Status Code” and “Error” entries. Update the
“Webhook logs page” list in the Call a webhook documentation so the “Status
Code” label uses proper spacing before the dash, and rephrase the “Error”
description to a clearer, concise sentence such as indicating it is the error
message or NULL on success.
- Around line 47-49: The heading and example sentence in the webhook flow docs
are awkward and repetitive; update the section title near the “Use webhook
response” text to read naturally without “the” before “flows,” and rephrase the
sentence in the “Call a webhook” content to remove the “you... and you want to”
wording. Use the existing webhook-response section text as the target and keep
the meaning while making it concise and clear.
- Line 64: The webhook docs example in the “Call a webhook” flow action uses a
Markdown-emphasized wildcard placeholder that renders incorrectly. Update the
text around the `@results.mywebhook.*YOUR_RESPONSE_OBJECT_KEY*` example to avoid
italic formatting by either wrapping the placeholder in backticks or rephrasing
it with angle brackets, so the `*` is preserved as an intentional meta-symbol
when readers view the rendered documentation.
---
Duplicate comments:
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md:
- Line 119: The branching guidance in this section uses a generic node name that
does not match the Glific UI. Update the wording in the webhook flow action docs
to use the exact node name “Split by a result in the flow” alongside “Wait for
result,” so the sentence in this section references the correct workflow node
name consistently.
- Line 74: Clarify the invalid-JSON behavior in the webhook response guidance so
authors know whether the Call a webhook step completes with an empty result or
errors and stops execution. Update the “How the response should be structured”
section near the JSON parsing rule for the webhook action, making the outcome
explicit for invalid JSON and keeping the wording aligned with the existing
“Return JSON” note.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 9744f649-2059-457d-8741-2232e563e24d
📒 Files selected for processing (1)
docs/4. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
| </table> | ||
| </h3> | ||
|
|
||
| **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.** |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Clarify the webhook description.
The current description conflates Glific's role as a WhatsApp Business API client (receiving incoming messages and delivery receipts) with the flow action "Call a webhook," which makes outbound HTTP requests from a flow to external APIs. This could confuse readers about what the webhook flow action actually does.
Consider rephrasing to focus on outbound calls to external APIs, e.g.:
Webhook calls let flows send data to external APIs and use the response in subsequent steps.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md at
line 11, The current webhook description in the flow action docs mixes inbound
WhatsApp handling with the outbound behavior of Call a webhook. Update the
description in the webhook flow action documentation to clearly state that this
action sends data from a flow to an external API and can use the response in
later steps, using the “Call a webhook” terminology to avoid confusion with
WhatsApp message reception.
| 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. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use precise terminology for the HTTP method dropdown.
Line 25 says "Choose POST in response type" but the dropdown selects the HTTP method (GET/POST), not a "response type." Update to:
- Choose
POSTas the HTTP method.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
around lines 24 - 28, The “Call a webhook” flow text uses the wrong term for the
dropdown selection; update the step in the webhook docs to refer to the HTTP
method instead of “response type.” In the “Call a webhook” section, revise the
instruction around the POST selection so it clearly says to choose POST as the
HTTP method, matching the dropdown behavior and terminology used elsewhere in
the flow actions docs.
| # 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. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Fix awkward heading and repetitive phrasing.
- Line 47: "Use webhook response in the flows" → "Use webhook response in flows" or "Using webhook responses in flows"
- Line 49: Static analysis flagged repetitive "you... and you want to" phrasing. Rephrase for clarity, e.g.:
After making a webhook call with the steps above, you can use the response variables in the flow.
🧰 Tools
🪛 LanguageTool
[style] ~49-~49: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...call (by using the above steps) and you want to use the response variable in the flow. ...
(REP_WANT_TO_VB)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
around lines 47 - 49, The heading and example sentence in the webhook flow docs
are awkward and repetitive; update the section title near the “Use webhook
response” text to read naturally without “the” before “flows,” and rephrase the
sentence in the “Call a webhook” content to remove the “you... and you want to”
wording. Use the existing webhook-response section text as the target and keep
the meaning while making it concise and clear.
Source: Linters/SAST tools
| > 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** |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
Escape or rephrase the wildcard placeholder.
The *YOUR_RESPONSE_OBJECT_KEY* uses asterisks that Markdown renders as italics, making the placeholder appear as @results.mywebhook.YOUR_RESPONSE_OBJECT_KEY without any visible wildcard marker. Readers may not realize * was intended as a meta-symbol. Use backticks or a different convention:
@results.mywebhook.<YOUR_RESPONSE_OBJECT_KEY>
or escape the asterisks: \*YOUR_RESPONSE_OBJECT_KEY\*
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md at
line 64, The webhook docs example in the “Call a webhook” flow action uses a
Markdown-emphasized wildcard placeholder that renders incorrectly. Update the
text around the `@results.mywebhook.*YOUR_RESPONSE_OBJECT_KEY*` example to avoid
italic formatting by either wrapping the placeholder in backticks or rephrasing
it with angle brackets, so the `*` is preserved as an intentional meta-symbol
when readers view the rendered documentation.
| 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. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
Fix formatting and awkward phrasing in the log fields list.
- Line 142:
`Status Code`-→ add space:`Status Code` - - Line 143: "Error is an error returned. NULL in the case of success" → rephrase to "Error message, or NULL if the call succeeded."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/4`. Product Features/03. Flows/2. Flow Actions/11. Call a webhook.md
around lines 137 - 146, The webhook logs field list has inconsistent formatting
and awkward wording in the “Status Code” and “Error” entries. Update the
“Webhook logs page” list in the Call a webhook documentation so the “Status
Code” label uses proper spacing before the dash, and rephrase the “Error”
description to a clearer, concise sentence such as indicating it is the error
message or NULL on success.
1 participant
…nd examples
Summary by CodeRabbit