> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/webhook.md).

# Webhook

Webhook callback integration：Send visitor messages and replies from Agents and human support staff on a conversation platform to your own system in real time—for customer service integration, real-tim

{% hint style="info" %}
**Setup guide**: This page covers one step in configuring a conversation platform. For the full text support launch process, see [Text Support: From Setup to Launch](https://docs.maiagent.ai/maiagent-user-guide/en/serve/text-service.md).
{% endhint %}

## Purpose <a href="#usage" id="usage"></a>

Webhooks are configured on a **conversation platform**. Once a developer provides an API endpoint (a URL), MaiAgent sends the message content to that URL whenever a message is created on the platform. This lets you integrate conversations into your own system, for example, to record them, forward them to users, or use them in other applications.

Each conversation platform can have multiple Webhooks, each with its own message direction:

| Type         | When delivery occurs                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------- |
| **Outgoing** | When a reply from an Agent or human support staff is created                                                  |
| **Incoming** | When a visitor message is created                                                                             |
| **Receive**  | When an external customer service platform sends messages back to MaiAgent (currently supports Genesys Cloud) |

The payload, response, and status code of each delivery are recorded for review and troubleshooting. See [View Delivery Records](#delivery-records) below.

{% hint style="info" %}
For payload fields, custom template syntax, and Webhook management through the API, ask your engineers to refer to [Webhook](https://docs.maiagent.ai/tech/serve/webhook) in the technical manual. To have your own customer service system take over conversations handed off to a human, see [Third-Party Customer Service System Integration (Including Human Handoff)](https://docs.maiagent.ai/tech/serve/customer-service-system-integration).
{% endhint %}

## Add a Webhook <a href="#add-webhook" id="add-webhook"></a>

### 1. Open Webhook Settings <a href="#open-webhook-settings" id="open-webhook-settings"></a>

Go to <mark style="color:blue;">Customer Service Conversations</mark> → <mark style="color:blue;">Conversation Platforms</mark>, click <mark style="color:blue;">Edit</mark> on the platform you want to configure, and open <mark style="color:blue;">Webhook Settings</mark>:

* **API platforms**: In the “Integration and Login” group in the left menu.
* **Messaging platforms such as LINE, Slack, and Microsoft Teams**: In the top tab bar.
* **Web and internal platforms** do not have this setting. To see which platforms support Webhooks, see the [Platform Support Matrix](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/platform-settings.md#platform-matrix).

### 2. Fill In the Webhook Fields <a href="#webhook-fields" id="webhook-fields"></a>

Click <mark style="color:blue;">Add Webhook</mark>, fill in the following fields, and save:

| Field                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Name</mark>           | A custom name for easy identification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| <mark style="color:blue;">Type</mark>           | <mark style="color:blue;">Outgoing</mark>, <mark style="color:blue;">Incoming</mark>, or <mark style="color:blue;">Receive</mark>. See the type descriptions above. Receive uses different fields; see [Fields for the Receive Type](#receive-fields) below                                                                                                                                                                                                                                                                         |
| <mark style="color:blue;">Enabled</mark>        | When disabled, deliveries stop, but the settings are retained                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| <mark style="color:blue;">Webhook URL</mark>    | The URL where your system receives data                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| <mark style="color:blue;">HTTP Method</mark>    | Use `POST` (default), `PUT`, or `PATCH`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| <mark style="color:blue;">Headers</mark>        | Custom headers included in every delivery, such as an API key required by your system                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| <mark style="color:blue;">Secret Token</mark>   | An optional signing secret. When configured, every delivery includes an HMAC signature and a timestamp header. Your system can use the same Secret Token to confirm that the request came from MaiAgent and that its content has not been tampered with. See [Verify the Delivery Source with a Secret Token](#secret-token) below. The value is not displayed after saving. When editing, leave it blank to keep the existing value; enter a new value to update it. This field is hidden when the payload format is Genesys Cloud |
| <mark style="color:blue;">Payload Format</mark> | <mark style="color:blue;">MaiAgent Standard</mark> (standard format), <mark style="color:blue;">Genesys Cloud</mark>, or a <mark style="color:blue;">Custom Template</mark> written in Jinja2 (available variables are listed in the form). When Genesys Cloud is selected, the Webhook URL and Headers are generated automatically from the [Genesys Cloud Integration](#genesys-cloud-integration) section below, and Secret Token is hidden                                                                                      |

#### Verify the Delivery Source with a Secret Token <a href="#secret-token" id="secret-token"></a>

**Example**: Acme Shopping wants to sync visitor messages from its website support channel to its own customer management system. Its engineers want the system to accept only data actually sent by MaiAgent. The support manager adds an <mark style="color:blue;">Incoming</mark> Webhook in the API platform’s <mark style="color:blue;">Webhook Settings</mark>, enters the customer management system’s receiving URL in <mark style="color:blue;">Webhook URL</mark>, enters the secret agreed with the engineers in <mark style="color:blue;">Secret Token</mark>, and clicks <mark style="color:blue;">Confirm</mark> to save. Every subsequent visitor message delivery includes a signature, and the engineers’ code rejects any delivery that fails verification.

1. Enter a secret in the <mark style="color:blue;">Secret Token</mark> field of the Webhook form, then click <mark style="color:blue;">Confirm</mark>. This field is available for all three types: <mark style="color:blue;">Outgoing</mark>, <mark style="color:blue;">Incoming</mark>, and <mark style="color:blue;">Receive</mark>.
2. Give the same secret to the engineers responsible for the receiving system. For signature header names and verification steps, see [Verify Signatures and Timestamps](https://docs.maiagent.ai/tech/serve/webhook#webhook-signature) in the technical manual.
3. To rotate the secret, click the edit icon in the Webhook list, enter a new value in <mark style="color:blue;">Secret Token</mark>, and save. This field is always blank when editing and never shows the current secret. Saving it blank keeps the existing secret.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-6c730a0a4bec48e3e687cfce34735c6769cc17d3%2Fchannels-webhook-secret-token.png?alt=media" alt="Secret Token field and its explanatory text in the Edit Webhook dialog"><figcaption><p>When editing a Webhook, the Secret Token field is blank. The text below explains that configuring it adds an HMAC signature and timestamp header, and that leaving it blank keeps the existing Secret Token</p></figcaption></figure>

{% hint style="info" %}
The admin interface has no option to clear a Secret Token; you can only replace it with a new value. Update the receiving system at the same time, or signatures on new deliveries will fail verification.
{% endhint %}

#### Fields for the Receive Type <a href="#receive-fields" id="receive-fields"></a>

<mark style="color:blue;">Receive</mark> works in the opposite direction: an external customer service platform sends messages **into** MaiAgent. Instead of entering your own URL, MaiAgent provides a receiving URL for the external platform:

| Field                                                   | Description                                                                                                                                                                             |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Default Payload Format</mark> | The format sent by the external platform. Currently supports <mark style="color:blue;">Genesys Cloud</mark> (conforming to the Genesys Cloud Open Messaging API format)                 |
| <mark style="color:blue;">Secret Token</mark>           | The secret used for signature verification. It must match the setting on the external platform. When editing, leave it blank to keep the existing value; enter a new value to update it |
| <mark style="color:blue;">Receiving URL</mark>          | Appears **only after saving**. Copy this URL and set it as the outbound webhook URL on the external platform                                                                            |

#### Genesys Cloud Integration <a href="#genesys-cloud-integration" id="genesys-cloud-integration"></a>

For Outgoing/Incoming Webhooks with <mark style="color:blue;">Genesys Cloud</mark> selected as the payload format, a “<mark style="color:blue;">Genesys Cloud Integration</mark>” section appears at the bottom of the form. Enter these settings once to apply them to all Genesys Cloud Webhooks on this conversation platform:

| Field                                                                                                 | Description                                                                                                                                                                                            |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <mark style="color:blue;">Region</mark>                                                               | The region of your Genesys Cloud organization                                                                                                                                                          |
| <mark style="color:blue;">OAuth Client ID</mark>/<mark style="color:blue;">OAuth Client Secret</mark> | Genesys Cloud OAuth Client Credentials, which must have the `conversation:message:create` permission. MaiAgent uses them to obtain a token automatically, so you do not need to enter Headers manually |
| <mark style="color:blue;">Integration ID</mark>                                                       | The Open Messaging Integration ID under Genesys Cloud Admin → Message → Platforms                                                                                                                      |

After filling in the fields, click <mark style="color:blue;">Test Connection</mark> to check that the credentials are valid, then save. If Genesys Cloud later reports invalid credentials, a warning appears above the Webhook list with the number of affected Webhooks. Click <mark style="color:blue;">Edit Integration Settings</mark>, re-enter the Client Secret, and save. <mark style="color:blue;">Remove Integration</mark> prevents the configured Genesys Cloud Webhooks from sending messages. For the full integration procedure, see [Third-Party Customer Service System Integration](https://docs.maiagent.ai/tech/serve/customer-service-system-integration) in the technical manual.

### 3. Verify Delivery <a href="#verify-delivery" id="verify-delivery"></a>

Send a message on the conversation platform, then check that the status code is 2xx in [Delivery Records](#delivery-records).

{% hint style="warning" %}
Account for the current delivery behavior when designing your system:

* **Signatures require a Secret Token**: Webhooks without a [Secret Token](#secret-token) send deliveries without a signature. To let the receiving system verify the source, configure a Secret Token and have the receiver verify the signature. Use an `https://` URL.
* **Temporary failures are retried automatically**: A delivery succeeds only when your system responds with 2xx. If there is no response within 30 seconds, the connection fails, or the response is 5xx or 429, delivery is retried after approximately 1, 5, and 15 minutes, up to 3 retries. Other 4xx responses, such as 400 and 404, are recorded as failures and are not retried. Each attempt has its own delivery record. Retries may deliver the same message more than once, so deduplicate messages by message ID on the receiving side. For details, see [Automatic Retries](https://docs.maiagent.ai/tech/serve/webhook#retry) in the technical manual.
* **Internal network addresses are rejected by default**: URLs on private subnets or internal networks cannot receive deliveries by default.
  {% endhint %}

## View Delivery Records <a href="#delivery-records" id="delivery-records"></a>

Go to <mark style="color:blue;">AI Features</mark> → <mark style="color:blue;">AI Assistants</mark>, select the Agent connected to this conversation platform, and switch to the <mark style="color:blue;">Webhook</mark> tab. The list shows the conversation ID, message ID, URL, status code, and creation time for each delivery. Click the view icon in the actions column to see the request preview, request JSON, and response content.

The Agent’s <mark style="color:blue;">Webhook</mark> tab contains only delivery records, collecting Webhook results from all conversation platforms under that Agent. To add, edit, or disable a Webhook, return to <mark style="color:blue;">Webhook Settings</mark> on the relevant conversation platform’s settings page (see [Add a Webhook](#add-webhook)). If an Agent connects to multiple platforms, use the conversation ID in the list to identify which platform the conversation belongs to.

## Use Cases <a href="#use-cases" id="use-cases"></a>

### **Customer Service System Integration** <a href="#customer-service-system-integration" id="customer-service-system-integration"></a>

After an Agent answers a user’s question, use a Webhook to sync the reply to your organization’s customer service system so support staff can review conversation records, follow up, or take over manually.

### **Real-Time Notifications** <a href="#real-time-notification-push" id="real-time-notification-push"></a>

Send Agent replies or specific events (such as anomalies) to communication tools such as Slack, Line Notify, and Email to alert the relevant staff to take action promptly.

### **Data Analytics and Archiving** <a href="#data-analytics-and-archiving" id="data-analytics-and-archiving"></a>

Automatically send all AI conversation data to a data warehouse, cloud database, or Google Sheets for usage analysis, quality evaluation, or interaction record archiving.

### **Internal Workflow Automation** <a href="#internal-workflow-automation" id="internal-workflow-automation"></a>

When users report issues, request resources, or report anomalies through an Agent, Webhooks can automatically send the data to internal form systems or task management tools (such as Jira and Notion) for follow-up tracking.

## Difference from Handoff Notifications <a href="#vs-handoff-notification" id="vs-handoff-notification"></a>

The Webhooks on this page deliver **individual messages**. To notify an external system when a conversation is handed off to a human, returned to AI, or times out in the queue, use [Webhook Notifications (System Integration)](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/human-handoff/handoff-notification.md#webhook) in the human handoff settings. The two features are configured independently.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/webhook.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
