> 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/ja/build/conversation-settings/webhook.md).

# Webhook

Webhook コールバック連携：会話プラットフォーム上の訪問者のメッセージと Agent・有人サポートの返信を自社システムへリアルタイムに送信し、カスタマーサポートシステム連携、リアルタイム通知、会話履歴のアーカイブ、社内ワークフローの自動化に活用できます。

{% hint style="info" %}
**設定ガイド**：このページでは、会話プラットフォームの設定手順の一部を説明します。テキストサポートの導入から運用開始までの流れは、[テキストサポート：ゼロから運用開始まで](https://docs.maiagent.ai/maiagent-user-guide/ja/serve/text-service.md)をご覧ください。
{% endhint %}

## 用途 <a href="#usage" id="usage"></a>

Webhook は**会話プラットフォーム**で設定します。開発者が API エンドポイント（URL）を指定すると、その会話プラットフォームでメッセージが作成されるたびに、MaiAgent がその URL へメッセージの内容を送信します。会話の記録、ユーザーへの転送など、自社システムとの連携やさまざまな用途に活用できます。

各会話プラットフォームには複数の Webhook を設定でき、それぞれで送信するメッセージの方向を指定できます。

| タイプ          | 送信のタイミング                                                                 |
| ------------ | ------------------------------------------------------------------------ |
| **Outgoing** | Agent または有人サポートの返信が作成されたときです                                             |
| **Incoming** | 訪問者のメッセージが作成されたときです                                                      |
| **Receive**  | 外部のカスタマーサポートプラットフォームから MaiAgent へメッセージを送信します（現在は Genesys Cloud に対応しています） |

送信ごとの内容、レスポンス、ステータスコードが記録されるため、確認やトラブルシューティングに利用できます。以下の[送信履歴の確認](#delivery-records)をご覧ください。

{% hint style="info" %}
送信内容のフィールド、カスタムテンプレートの書き方、API による Webhook 管理については、技術マニュアルの [Webhook](https://docs.maiagent.ai/tech/serve/webhook) を担当エンジニアにご案内ください。自社のカスタマーサポートシステムで有人対応に切り替えた会話を引き継ぐ場合は、[サードパーティ製カスタマーサポートシステム連携（有人対応への切り替えを含む）](https://docs.maiagent.ai/tech/serve/customer-service-system-integration)をご覧ください。
{% endhint %}

## Webhook の追加 <a href="#add-webhook" id="add-webhook"></a>

### 1. Webhook 設定を開く <a href="#open-webhook-settings" id="open-webhook-settings"></a>

<mark style="color:blue;">カスタマーサポートの会話</mark> → <mark style="color:blue;">会話プラットフォーム</mark>に進み、設定するプラットフォームの<mark style="color:blue;">編集</mark>をクリックして、<mark style="color:blue;">Webhook 設定</mark>を開きます。

* **API プラットフォーム**：左側メニューの「連携とログイン」グループにあります。
* **LINE、Slack、Microsoft Teams などのメッセージングプラットフォーム**：上部のタブバーにあります。
* **Web・内部プラットフォーム**にはこの設定はありません。Webhook 設定に対応するプラットフォームについては、[プラットフォーム対応表](https://docs.maiagent.ai/maiagent-user-guide/ja/build/conversation-settings/platform-settings.md#platform-matrix)をご覧ください。

### 2. Webhook の各フィールドを入力する <a href="#webhook-fields" id="webhook-fields"></a>

<mark style="color:blue;">Webhook を追加</mark>をクリックし、以下のフィールドを入力して保存します。

| フィールド                                         | 説明                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">名前</mark>           | 識別しやすい任意の名前を指定します                                                                                                                                                                                                                                                                                                                |
| <mark style="color:blue;">タイプ</mark>          | <mark style="color:blue;">Outgoing</mark>、<mark style="color:blue;">Incoming</mark>、<mark style="color:blue;">Receive</mark> から選びます。各タイプについては上記の説明をご覧ください。Receive を選ぶとフィールドが異なります。以下の [Receive タイプのフィールド](#receive-fields)をご覧ください                                                                                                |
| <mark style="color:blue;">有効状態</mark>         | 無効にすると送信を停止しますが、設定は保持されます                                                                                                                                                                                                                                                                                                        |
| <mark style="color:blue;">Webhook URL</mark>  | 自社システムがデータを受信する URL です                                                                                                                                                                                                                                                                                                           |
| <mark style="color:blue;">HTTP Method</mark>  | `POST`（デフォルト）、`PUT`、`PATCH` を使用します                                                                                                                                                                                                                                                                                               |
| <mark style="color:blue;">Headers</mark>      | 自社システムが要求する API キーなど、送信のたびに付与するカスタムヘッダーです                                                                                                                                                                                                                                                                                        |
| <mark style="color:blue;">Secret Token</mark> | 任意の署名用シークレットです。設定すると、送信のたびに HMAC 署名とタイムスタンプのヘッダーが付与されます。受信側は同じ Secret Token を使い、リクエストが MaiAgent から送信され、内容が改ざんされていないことを確認できます。以下の [Secret Token による送信元の検証](#secret-token)をご覧ください。保存後は値が表示されません。編集時に空欄のままにすると既存の値が保持され、新しい値を入力した場合のみ更新されます。Payload 形式が Genesys Cloud の場合、このフィールドは表示されません                                           |
| <mark style="color:blue;">Payload 形式</mark>   | <mark style="color:blue;">MaiAgent Standard</mark>（標準形式）、<mark style="color:blue;">Genesys Cloud</mark>、または Jinja2 で記述する<mark style="color:blue;">カスタムテンプレート</mark>を選びます（利用可能な変数はフォームに表示されます）。Genesys Cloud を選ぶと、Webhook URL と Headers は下部の [Genesys Cloud 連携](#genesys-cloud-integration)セクションから自動生成され、Secret Token も表示されなくなります |

#### Secret Token による送信元の検証 <a href="#secret-token" id="secret-token"></a>

**利用例**：「Acme ショッピング」では、公式サイトのサポート窓口に届く訪問者のメッセージを自社の顧客管理システムに同期したいと考えています。エンジニアは、MaiAgent が実際に送信したデータだけを受け付けるようにしたいと考えています。サポート責任者は API プラットフォームの <mark style="color:blue;">Webhook 設定</mark>で <mark style="color:blue;">Incoming</mark> Webhook を追加し、<mark style="color:blue;">Webhook URL</mark> に顧客管理システムの受信 URL、<mark style="color:blue;">Secret Token</mark> にエンジニアと取り決めたシークレットを入力して、<mark style="color:blue;">確認</mark>をクリックして保存します。以後、訪問者の各メッセージの送信に署名が付与され、エンジニアのプログラムは検証に失敗したデータを拒否します。

1. Webhook フォームの <mark style="color:blue;">Secret Token</mark> フィールドにシークレットを入力し、<mark style="color:blue;">確認</mark>をクリックします。<mark style="color:blue;">Outgoing</mark>、<mark style="color:blue;">Incoming</mark>、<mark style="color:blue;">Receive</mark> の3タイプすべてにこのフィールドがあります。
2. 同じシークレットを受信側の担当エンジニアに渡します。署名ヘッダーの名前と検証手順については、技術マニュアルの[署名とタイムスタンプの検証](https://docs.maiagent.ai/tech/serve/webhook#webhook-signature)をご覧ください。
3. シークレットを変更するには、Webhook 一覧の編集アイコンをクリックし、<mark style="color:blue;">Secret Token</mark> に新しい値を入力して保存します。編集時、このフィールドは常に空欄で、現在のシークレットは表示されません。空欄のまま保存すると既存のシークレットが保持されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-6c730a0a4bec48e3e687cfce34735c6769cc17d3%2Fchannels-webhook-secret-token.png?alt=media" alt="Webhook 編集ダイアログの Secret Token フィールドとその下の説明"><figcaption><p>Webhook の編集時、Secret Token フィールドは空欄です。下の説明には、設定すると HMAC 署名とタイムスタンプのヘッダーが付与されることと、空欄のままにすると既存の Secret Token が保持されることが記載されています</p></figcaption></figure>

{% hint style="info" %}
管理画面には Secret Token を消去するオプションはなく、新しい値への変更のみ可能です。変更時は受信側も同時に更新してください。更新しないと、新たな送信の署名が一致しなくなります。
{% endhint %}

#### Receive タイプのフィールド <a href="#receive-fields" id="receive-fields"></a>

<mark style="color:blue;">Receive</mark> は逆方向の連携です。外部のカスタマーサポートプラットフォームから MaiAgent **へ**メッセージを送信するため、自社の URL を入力する代わりに、MaiAgent が外部プラットフォーム用の受信 URL を提供します。

| フィールド                                             | 説明                                                                                                                       |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| <mark style="color:blue;">Payload のデフォルト形式</mark> | 外部プラットフォームから送信される形式です。現在は <mark style="color:blue;">Genesys Cloud</mark>（Genesys Cloud Open Messaging API 形式に準拠）に対応しています |
| <mark style="color:blue;">Secret Token</mark>     | 署名検証に使用するシークレットです。外部プラットフォームの設定と一致させてください。編集時に空欄のままにすると既存の値が保持され、新しい値を入力した場合のみ更新されます                                     |
| <mark style="color:blue;">受信 URL</mark>           | **保存後**に表示されます。この URL をコピーし、外部プラットフォームの outbound webhook URL に設定します                                                      |

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

Payload 形式に <mark style="color:blue;">Genesys Cloud</mark> を選んだ Outgoing／Incoming Webhook では、フォーム下部に「<mark style="color:blue;">Genesys Cloud 連携</mark>」セクションが表示されます。一度入力すると、この会話プラットフォーム内のすべての Genesys Cloud Webhook に適用されます。

| フィールド                                                                                                 | 説明                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| <mark style="color:blue;">リージョン</mark>                                                                | Genesys Cloud 組織が属するリージョンです                                                                                                                |
| <mark style="color:blue;">OAuth Client ID</mark>／<mark style="color:blue;">OAuth Client Secret</mark> | Genesys Cloud の OAuth Client Credentials です。`conversation:message:create` 権限が必要です。MaiAgent がこれを使って自動的にトークンを取得するため、Headers を手動で入力する必要はありません |
| <mark style="color:blue;">Integration ID</mark>                                                       | Genesys Cloud Admin → Message → Platforms にある Open Messaging Integration ID です                                                             |

入力後、<mark style="color:blue;">接続テスト</mark>をクリックして認証情報が有効か確認し、保存します。その後、Genesys Cloud から認証情報が無効と報告された場合、Webhook 一覧の上部に警告と影響を受ける件数が表示されます。<mark style="color:blue;">連携設定を変更</mark>をクリックし、Client Secret を再入力して保存してください。<mark style="color:blue;">連携を削除</mark>すると、設定済みの Genesys Cloud Webhook からメッセージを送信できなくなります。連携手順の詳細は、技術マニュアルの[サードパーティ製カスタマーサポートシステム連携](https://docs.maiagent.ai/tech/serve/customer-service-system-integration)をご覧ください。

### 3. 送信を確認する <a href="#verify-delivery" id="verify-delivery"></a>

会話プラットフォームでメッセージを1件送信し、[送信履歴](#delivery-records)でステータスコードが 2xx であることを確認します。

{% hint style="warning" %}
システム設計には、現在の以下の送信動作を考慮してください。

* **署名には Secret Token の設定が必要です**：[Secret Token](#secret-token) を設定していない Webhook の送信には署名が付きません。受信側で送信元を確認するには、Secret Token を設定し、受信側で署名を検証してください。URL には `https://` を使用してください。
* **一時的な失敗は自動的に再送されます**：自社システムが 2xx を返した場合のみ成功となります。30秒以内に応答がない場合、接続できない場合、または 5xx・429 が返された場合は、約1分、5分、15分後にそれぞれ再送し、再送は最大3回です。400・404 など、それ以外の 4xx は失敗として記録され、再送されません。各試行は送信履歴に個別に記録されます。再送によって同じメッセージが複数回届く可能性があるため、受信側でメッセージ ID を使って重複を排除してください。詳細は、技術マニュアルの[自動再送](https://docs.maiagent.ai/tech/serve/webhook#retry)をご覧ください。
* **内部ネットワークのアドレスはデフォルトで拒否されます**：プライベートネットワークや内部ネットワークの URL は、デフォルトでは送信を受信できません。
  {% endhint %}

## 送信履歴の確認 <a href="#delivery-records" id="delivery-records"></a>

<mark style="color:blue;">AI 機能</mark> → <mark style="color:blue;">AI アシスタント</mark>に進み、この会話プラットフォームに接続している Agent を選択して、<mark style="color:blue;">Webhook</mark> タブに切り替えます。一覧には、各送信の会話 ID、メッセージ ID、URL、ステータスコード、作成日時が表示されます。操作列の表示アイコンをクリックすると、リクエストのプレビュー、リクエスト JSON、レスポンス内容を確認できます。

Agent の <mark style="color:blue;">Webhook</mark> タブには送信履歴のみが表示され、その Agent に紐づくすべての会話プラットフォームの Webhook 結果が集約されます。Webhook の追加・変更・無効化は、各会話プラットフォームの設定ページにある <mark style="color:blue;">Webhook 設定</mark>で行ってください（[Webhook の追加](#add-webhook)を参照）。同じ Agent が複数のプラットフォームに接続されている場合は、一覧の会話 ID でどのプラットフォームの会話かを確認してください。

## 活用例 <a href="#use-cases" id="use-cases"></a>

### **カスタマーサポートシステム連携** <a href="#customer-service-system-integration" id="customer-service-system-integration"></a>

Agent がユーザーの質問に回答した後、Webhook で返信内容を企業のカスタマーサポートシステムに同期します。担当者は会話履歴の確認、フォローアップ、有人対応への引き継ぎを行えます。

### **リアルタイム通知** <a href="#real-time-notification-push" id="real-time-notification-push"></a>

Agent の返信や特定のイベント（異常など）を Slack、Line Notify、Email などのコミュニケーションツールに送信し、担当者に迅速な対応を促します。

### **データ分析と記録のアーカイブ** <a href="#data-analytics-and-archiving" id="data-analytics-and-archiving"></a>

すべての AI 会話データをデータウェアハウス、クラウドデータベース、Google Sheets に自動送信し、利用行動の分析、品質評価、対話履歴のアーカイブに活用できます。

### **社内ワークフローの自動化** <a href="#internal-workflow-automation" id="internal-workflow-automation"></a>

ユーザーが Agent を通じて問題の報告、リソースの申請、異常の報告を行うと、Webhook がそのデータを社内フォームシステムやタスク管理ツール（Jira、Notion など）に自動連携し、その後の追跡に利用できます。

## 有人対応への切り替え通知との違い <a href="#vs-handoff-notification" id="vs-handoff-notification"></a>

このページの Webhook は**メッセージ単位**で送信します。会話が有人対応に切り替わったとき、AI に戻されたとき、待ち行列でタイムアウトしたときに外部システムへ通知するには、有人対応への切り替え設定の [Webhook 通知（システム連携）](https://docs.maiagent.ai/maiagent-user-guide/ja/build/conversation-settings/human-handoff/handoff-notification.md#webhook)を使用してください。両者の設定は独立しています。


---

# 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/ja/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.
