> For the complete documentation index, see [llms.txt](https://en.help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en.help.firstline.cc/feature/chatbot/scenario/example/webhook-integration-guide.md).
# Webhook integration guide
## Overview
When you**call external services via Webhook in a bot flow**, if the request times out due to the following reasons:
* Technical implementation not yet optimized
* Too many steps executed in a single call and**need to wait for a response**(such as synchronously creating an order, writing to a database, etc.)
* Insufficient server performance or high latency
it may cause the Webhook to not receive a response within the specified wait time, resulting in a timeout error.
For example: In the flow, when calling an API to create an order, if that API only returns a result after the entire creation process completes, it can easily cause the Webhook request to exceed the waiting limit.
This article will explain several**ways to improve Webhook integration performance and stability**, helping to avoid timeout issues caused by packing too much processing into a single request.
{% hint style="warning" %}
## **Bot flow integration reminder**
**When you call a Webhook in a bot flow, the flow will pause and wait for the Webhook response to complete, and customer messages during this period will not be further triggered for processing**.
For example: When a customer indicates they want to look up information and an external service is called via Webhook to handle it, if the response time is long and the customer keeps adding messages while waiting, these messages**will not be delivered or processed in real time**, which may lead to broken context and disjointed responses.
If you intend to integrate a third-party Large Language Model (LLM), be sure to consider the above limitations and assess whether they meet your needs for real-time interaction and conversational completeness.
***
**In an actual conversation flow, making customers wait more than 10 seconds without any follow-up response will severely impact the interaction experience and trust, which is an unacceptable scenario in design.**
**When designing flow integrations or API calls, be sure to prioritize user experience. The purpose of integration should be to improve responsiveness and consistency, rather than sacrificing the overall experience purely for technical feasibility or attempts to “break system limits.”**
* **If the integration process requires a longer time, you can design intermediate replies (e.g., “Please wait while we are querying”).**
{% endhint %}
## ✅ Break down steps, process asynchronously
To avoid the Webhook executing too many operations that require waiting in a single call (such as creating orders, connecting to external systems), which may cause request timeouts, we recommend the following approach:
**Break down multiple processing steps and execute them in stages:**
1. After calling the API in the flow,**return immediately `200 OK`**, to avoid blocking or long waits that cause timeouts.
2. Then insert a **“Wait” node**, for example a 20-second delay, to allow time for external processing.
3. After the wait ends, use another **Webhook node or API call**, to proactively query or try to obtain the processing result.
With this design, you can effectively avoid timeout issues caused by handling too much logic synchronously at once, while retaining flow control and follow-up chaining capability.
## ✅ Advanced suggestion: Message node design to enhance customer experience
In the above flow, if you want customers to feel that the process is ongoing and not a system delay, you can also add a**message prompt node**to optimize the experience:
* **Before the wait node, insert a “Send Message” node**, proactively informing the customer of the current processing progress\
For example: “The order is being created, please wait...”
This design not only reduces uncertainty during the waiting period, but also helps lower repeated inquiries or interrupted actions caused by waiting.
## ✅ Advanced technique: Combine Webhook return results + conditional judgment nodes
If your external system’s response time is variable, it’s recommended to further design a set of**response result judgment logic**to enhance flow flexibility and response efficiency:
**📌 Implementation approach:**
1. **During the first Webhook call**, have the external system return a piece of result information, for example:
```json
{
"result": "success",
"order_id": "123456"
}
```
2. **Insert a conditional judgment node in the flow**and determine based on the `result` value in the returned data:
* If it is `success`, then proceed directly to the subsequent response flow to display the result or notify the user
* If it is `pending` / `null` / `failed`, then follow the original wait + recheck path (e.g., call the webhook again after waiting 20 seconds to query)
This design can**effectively reduce unnecessary waiting time**, allowing successful flows to**end immediately and respond to the user**, while for failed or incomplete cases, proceed further via waiting and recheck mechanisms**for additional handling**.
Overall, this approach provides greater flexibility to**cope with unstable response times from external systems**, while also achieving a**stable, uninterrupted, and predictable**integration experience. It is one of the highly recommended advanced integration strategies in practice.
## Summary
The use of Webhooks is affected by the following limiting rules: including the maximum number of triggers per minute, the maximum waiting time for a single request, and the maximum number of requests being processed simultaneously (concurrency limit), etc.
If you apply Webhooks in high-frequency request scenarios, pay special attention to potential queuing effects. For example:**If the average response time per request approaches 15 seconds, other requests in the queue will also be forced to wait in sequence for the previous one to complete, leading to a cascading latency effect**, significantly reducing overall response efficiency.
Therefore, we still recommend that you design the webhook structure according to standard flows and adopt approaches like quick responses and background processing to optimize integration efficiency.
{% hint style="warning" %}
#### ⚠️ Potential impacts of long delayed responses
1. **LINE Reply Token limitation:**If you are integrating with **LINE Official Account**please note that its Reply Token is only valid for about **30 seconds**. If the Webhook cannot complete the response within this time, real-time replies cannot complete the interaction, and you will need to resend via push messages,**which may incur additional costs and a gap in user experience**.
2. **Conversion rate and user experience loss:**Delayed interaction responses will directly affect users’ retention and actions in the sales flow, potentially causing: users to leave midway or abandon form completion, reduced satisfaction with customer service responses, and loss of actual conversion rate and revenue
3. **Decreased platform credibility and risk of technical penalties**: Some third-party platforms (such as Slack, Facebook, Stripe, etc.) set strict requirements for webhook response times to ensure overall service quality. If the integrator fails to complete the response within the specified time limit, the platform may deem the service unstable and trigger technical penalty mechanisms, such as lowering the webhook notification frequency or pausing event delivery.
4. **Cascading latency effect**: When webhook response times are too high (e.g., more than 40 seconds), queuing effects will occur, causing delays in subsequent message processing. Especially in scenarios where only a limited number of concurrent webhook processes are allowed, if multiple users interact simultaneously, the system will process them in sequence, resulting in the second and third customers’ messages being delayed by tens of seconds or even more than a minute. This significantly impacts overall response timeliness, reduces user experience, and further amplifies the risks of platform response timeouts and conversion loss.
...etc. We recommend that you optimize the integration architecture and adopt a fast response mechanism; otherwise, subsequent issues such as message loss, interaction errors, or platform penalties may occur.
{% endhint %}
