> 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: push visitor messages and Agent or human-agent replies from a conversation platform to your own system in real time—for customer service system integration, instant notif

{% hint style="info" %}
**Guide navigation**: This page is one step of conversation platform setup. For the complete go-live flow for text customer service, see [Text Customer Service: From Zero to Live](/maiagent-user-guide/en/serve/text-service.md).
{% endhint %}

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

A Webhook is configured on a **conversation platform**. After a developer provides an API endpoint (a URL), MaiAgent sends the message content to that URL every time this conversation platform creates a message, so you can integrate conversations into your own system—for example, to log them, forward them to users, or use them in other applications.

Each conversation platform can have multiple Webhooks, each deciding which direction of messages to push:

| Type         | When it is pushed                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| **Outgoing** | When a reply from an Agent or a human agent is created                                                   |
| **Incoming** | When a visitor's message is created                                                                      |
| **Receive**  | An external customer service platform sends messages back to MaiAgent (currently supports Genesys Cloud) |

The content, response, and status code of every push are recorded so you can review them and troubleshoot problems. See [View delivery records](#delivery-records) below.

{% hint style="info" %}
For the payload fields, how to write custom templates, and how to manage Webhooks through the API, ask your engineer to refer to [Webhook](https://docs.maiagent.ai/tech/serve/webhook) in the technical manual. To have your own customer service system take over handoffs to human agents, 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 the 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 conversation platform you want to configure, and open <mark style="color:blue;">Webhook Settings</mark>:

* **API platform**: In the "Integration and Login" group in the left menu.
* **Messaging platforms such as LINE, Slack, and Microsoft Teams**: In the tab bar at the top.
* **Web and internal platforms** do not have this setting. For which platforms have Webhook settings, see the [Platform support matrix](/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. The fields differ when you choose Receive; see [Fields for the Receive type](#receive-fields) below                                                                                                                                       |
| <mark style="color:blue;">Status</mark>         | When turned off, nothing is pushed, but the settings are kept                                                                                                                                                                                                                                                                                                                                                 |
| <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 attached to every push, for example an API key required by your system                                                                                                                                                                                                                                                                                                                         |
| <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 (the form lists the available variables). When you choose Genesys Cloud, the Webhook URL and Headers are generated automatically from the [Genesys Cloud integration](#genesys-cloud-integration) section below |

#### 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, so you do not enter your own URL. Instead, MaiAgent provides a receiving URL for the other party:

| Field                                                   | Description                                                                                                                                                                               |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Default Payload Format</mark> | The format the other party sends. Currently supports <mark style="color:blue;">Genesys Cloud</mark> (matching 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 other platform. When editing, leaving it blank keeps the existing value, and entering a new value updates it |
| <mark style="color:blue;">Receiving URL</mark>          | Shown 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 the Payload Format set to <mark style="color:blue;">Genesys Cloud</mark>, a "<mark style="color:blue;">Genesys Cloud Integration</mark>" section appears below the form. Fill it in once and it applies to all Genesys Cloud Webhooks under this conversation platform:

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

After filling these in, click <mark style="color:blue;">Test Connection</mark> to confirm the credentials are valid, and then save. If Genesys Cloud later reports that the credentials are invalid, a warning appears above the Webhook list showing the number of affected entries. 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 complete integration steps, 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 in the [delivery records](#delivery-records) that the status code is 2xx.

{% hint style="warning" %}
Take the current delivery behavior into account in your system design:

* **No signature**: Pushes do not carry a signature computed over the content. To let the receiving end confirm the source, add a mutually agreed value to <mark style="color:blue;">Headers</mark> and use an `https://` URL.
* **No retry on failure**: A push succeeds only when your system responds with 2xx. No response within 30 seconds, or a non-2xx response, is recorded as a failure and is not resent automatically. If you need reliable delivery, store the data on the receiving end before responding with 2xx.
* **Internal network addresses are rejected by default**: URLs on private network ranges or internal addresses cannot receive pushes 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 of every push. Click the view icon in the actions column to see the request preview, the request JSON, and the response content.

The Agent's <mark style="color:blue;">Webhook</mark> tab contains delivery records only, aggregating the Webhook results of all conversation platforms under this Agent. To add, edit, or disable a Webhook, go back to the <mark style="color:blue;">Webhook Settings</mark> on each conversation platform's settings page (see [Add a Webhook](#add-webhook)). When one Agent is connected to multiple platforms, use the conversation ID in the list to trace which platform a 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 the Agent answers a user's question, a Webhook syncs the reply to the company's customer service system, so support staff can review the conversation history, follow up, or take over manually.

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

Push Agent replies or specific events (such as abnormal situations) to communication tools such as Slack, Line Notify, and Email, to remind the relevant people to act immediately.

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

Automatically send all AI conversation data to a data warehouse, a 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, a Webhook can automatically pass this 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 Webhook on this page pushes data per **message**. To notify an external system when a conversation is handed to a human, handed back to AI, or the queue times out, use [Webhook Notification (System Integration)](/maiagent-user-guide/en/build/conversation-settings/human-handoff/handoff-notification.md#webhook) in the human handoff settings instead. The two 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.