⛓️Webhook scripts

Overview

Integrating the system with third-party services via custom webhook scripts helps streamline complex workflows and improve overall system efficiency. This approach allows you to define custom behavior in response to specific events, making the system more flexible and adaptable to particular requirements. Integrating webhooks enables real-time data transmission, promotes collaboration between systems, and simplifies data processing, delivering a better user experience.

The concept of webhooks is based on an event-driven architecture: when a specific event occurs, the system proactively notifies the registered webhook URL for that event. Therefore, when using webhook scripts, you need to understand how to configure the webhook URL and how to handle the received event notifications.

Before using webhook scripts, it is recommended that you have basic API integration skills, including an understanding of how to make requests to RESTful APIs and some basic configurations such as header settings and params. If you have used Postman or other API testing tools, that experience will help you understand how webhooks operate.

If you are not yet familiar with API integration, we recommend you first learn some related basic concepts and operations to ensure smooth use of webhook scripts for third-party service integration.

Create a Webhook Script

Add Script

You can follow these steps to add a webhook script:

1. Go to the "Applications" feature.

2. Find the "Integrations" category within Applications.

3. Click the "Webhook Scripts" feature.

4. Look for the "Add" button in the interface and click it.

This lets you start adding your first automation entry. During the addition process, you may need to fill in some required information, such as "Select use case", "Name", etc. Follow the system prompts to complete adding the webhook script.

Name	Description
Select Use Case	The use case determines which related data you can read and cannot be changed after creation. You can choose scenarios like "Contact", "Ticket", etc.
Name	Identifier name for the webhook script.

Configure Request Method

The Request settings in the interface can be broadly divided into three sections: URL, Params, and Headers. These compose an API request, and the items in each section are as follows:

URL section:

• Request API path URL: Defines the API endpoint or resource location. For example,https://api.example.com/users.

• Method (request method): Represents the operation on that URL, including GET (retrieve data), POST (create data), PUT (update data), DELETE (delete data), etc.

Header:

Used to set additional parameters in the header. Common items include the following information

• User-Agent: Informs the server about the client making the request, including browser, operating system, etc.

• Accept: Informs the server about the response content types the client can accept.

• Content-type: Informs the server about the content type the client is submitting, especially in POST or PUT requests.

These elements together form a complete API request, ensuring correct and effective information exchange.

Params

Params are parameters set in an API request, often used to define specific search criteria, filters, or other values that need to be specified in the API request. The system provides corresponding "placeholders" for different events, which is a flexible feature that allows related data to be injected into parameters.

For example, in the "Contact" use case, you can enter in Params {{ contact.first_name }}so that when the corresponding event is triggered, the system will automatically insert the contact's first name into that parameter.

This mechanism provides a more dynamic and personalized API request method, allowing you to operate and utilize related data more effectively.

"Placeholders" might not display all the custom data fields you defined; for example:

1. For variables in a conversation script, suppose you set a variable named has_message in the script, you may need to manually input into the params section {{ has_message }} to pass the data.

2. For custom field data, for example if you created a custom field named "Height", you can enter {{czCol.15 }} to pass the data. The number 15 here is the system ID for the "Height" custom field and can be found in the custom fields interface. Note that depending on the trigger source, a prefix may be required. For example, for the "Contact" source, you do not need to add the contact prefix because it is the trigger source itself and corresponds to itself. But for other sources, to get a contact's custom field data, you would need to use {{ contact.czCol.15 }}.

Please note that these methods may be deprecated in the future, so we recommend you pay attention to our update announcements to get the latest information.

System ID, which you can find in the custom fields interface.

Triggering Webhook Scripts

After you have added a webhook script, you can trigger it using the following methods:

1. Trigger via "Automation Scripts": In different scenarios, you can use the "Automation Scripts" feature, for example when a ticket is created or under other specific conditions, to trigger the corresponding webhook script.

2. Trigger via a "Conversation Script" action node: If you use a chatbot, you can use an action node in the conversation flow of a "Conversation Script" to trigger a specific webhook script. This can be triggered according to different chatbot contexts and flows.

These triggering methods provide flexibility, allowing you to use webhook scripts effectively according to needs and context.

To prevent abuse of system resources or excessive triggering that exceeds system processing capacity, we set per-minute trigger limits, wait time limits, and dynamic control of retry counts for webhooks to ensure fair usage of system resources by all users and maintain overall platform stability. Note that these limits are intended to prevent abuse in certain situations.For example, if you set a webhook to trigger when a contact is updated and then use the webhook to call an API that updates the same contact record, this may create an infinite loopwhich could trigger the limit mechanism. Under normal usage, you should rarely encounter trigger count limit issues.

Request limits and notes

When the system executes a webhook script and calls the request path you configured, please pay special attention to the following execution rules:

1. Response time limit:Requests should complete their response within 5 - 10 seconds, otherwise they will be considered timed out and treated as failures.

Actual retry counts and interval times will be dynamically adjusted based on current system load, with the shortest response time limit being 5 seconds.

Best practice recommendations

👋 Hello! This is a message from the technical team.

Previously, our webhook design adopted aflexible wait time range of 5–80 seconds ^[1] based on providing fault tolerance when server resources were abundant. But in practice we found that this flexible arrangementcaused user misunderstandings and confusion^[2]and led to misconceptions about integration behavior, which was not the original intent. Therefore, we decided toimplement a unified fixed wait timeto improve stability and consistency of expectations.

---

To help you integrate webhooks smoothly and reduce the risk of timeouts, please follow these principles tooptimize your application and server design:

• Keep processing logic as simple as possible After receiving a request, keep the processing flow as short as possible. After validating the payload data, quickly execute the necessary logic and avoid excessive checks and redundant validations.

• Avoid synchronous blocking operations Avoid performing unnecessary synchronous operations during webhook execution, such as writing large amounts of data, calling external APIs, or generating reports, as these actions will cause overall delays.

• Move high-latency or nonessential actions out of the main flow Non-real-time-required operations (such as notifications, report generation, large data processing, etc.) should be handled after the webhook response is successful, to avoid blocking the main flow.

• Avoid multi-layer chaining and waiting flows Avoid chaining too many systems and waiting for responses during webhook execution,for example: webhook call → execute business logic → call other APIs → wait for processing to complete → return, it is recommended to respond 200 OK immediately upon receiving the request and handle subsequent work via asynchronous mechanisms. If integrating with bots or automation flows, it is recommended to split the logic into multiple nodes rather than performing all steps in a single webhook call.

• Immediately respond once preliminary validation is complete After completing basic data format and signature/token validation, respond success immediately to ensure the webhook sender does not time out from waiting too long.

• Delegate complex tasks to background processing or queue systems Large or non-real-time tasks should be executed via background processing tools (such as RabbitMQ, Celery, etc.) to ensure the webhook main flow responds quickly and is not held up.

• Check server load status If data formats, data volume, or request volume have not clearly increased or changed but responses become slow or unstable, check whether the server's CPU, memory, disk, or network resources are near capacity, and assess whether rate limiting, upgrading, or horizontal scaling of servers is needed.

etc. Check and reinforce your code and server logic to improve the overall reliability and processing efficiency of webhook integrations.

---

_{^[1] max(5, min(80, 80 × (1 - load_rate)))}

_{^[2] This was mentioned in the release notes for version 2.74.09}