# Webhooks

Webhookを使用すると、新しい連絡先の作成、予約の確定、メッセージの受信など、重要なイベントが発生した際に、<span data-t="appName">Your AI Connector</span>から他のビジネスツールへ自動的に通知を送ることができます。手動で更新を確認する必要はなく、何かが発生した瞬間に接続先のシステムへ即座に通知が届きます。


---

## Webhooksとは？

Webhookは、2つのアプリ間で行われる自動テキストメッセージのようなものだと考えてください。<span data-t="appName">Your AI Connector</span>で何らかのイベント（新しい連絡先の登録など）が発生すると、プラットフォームは即座に指定した別のシステムへ通知を送信します。通知の送信先となるWebアドレス（「Webhook URL」と呼ばれます）を指定してください。これは通常、CRM、自動化プラットフォーム、または開発者から提供されます。

> **Webhookは<span data-t="appName">Your AI Connector</span>からデータを送信するのみです。** Webhookは<span data-t="appName">Your AI Connector</span>から他のツールへ向かう一方通行の仕組みです。リード、連絡先、またはメッセージをプラットフォーム**内へ**送信するWebhook URLは存在しません。Webサイトのフォーム、CRM、またはGoHighLevelなどから新しいリードをプッシュするには、代わりに**API呼び出し**を行います。[APIアクセス](api-access.md)（*連絡先の作成*操作）および[ファネル](funnels.md)を参照してください。インバウンド方向（受信）に必要なものは**APIキー**のみであり、これは専用のセクションにあります。[APIアクセス](api-access.md#generating-your-api-key)を参照してください。ここで説明されている**Webhook**ページは、アウトバウンド方向（送信）専用です。

::: note
**注意:** Webhookの設定には技術的な構成が必要です。操作に不安がある場合は、このページを開発者に共有するか、Zapier、Make、Pabblyなどの自動化プラットフォームを使用してください。これらを使用すれば、コーディングなしでWebhook URLを取得できます。
:::


一般的な用途は以下の通りです：

- 新しい連絡先をCRMに同期する。
- タグが付与された際に、Zapier、Make、またはPabblyでワークフローをトリガーする。
- 人間による対応が必要になった際に、Slackでチームに通知する。
- 予約が確定した際に、カレンダーシステムを更新する。
- 会話の要約をデータベースに記録する。

---

## Webhookの設定方法

1. 左側のサイドバーで、**設定**（歯車アイコン）をクリックします。
2. 設定サイドバーの**統合**グループの下にある**Webhook**をクリックします。


Webhookがまだ設定されていないアカウントでは、ページは次のように表示されます。


3. 右上の **New webhook** をクリックします。ページ内にフォームが開きます：


4. 以下を入力します：
   - **エンドポイントURL** — <span data-t="appName">Your AI Connector</span>がイベント通知を送信するWebアドレス。外部システム（CRM、自動化プラットフォーム、またはカスタムサーバー）から取得します。
   - **名前** — 後で判別するためのラベル（例：「Slackアラート」や「CRM同期」など）。自分用の参照ラベルです。

> **Webhook URLは、パブリックにアクセス可能な `https://` アドレスである必要があります。** `http://` アドレス、`localhost` またはプライベートネットワークのアドレス、およびプラットフォーム内部のアドレスは、保存時に拒否されます。自分のマシンからテストする場合は、localhostの代わりにパブリックトンネル（webhook.siteやngrokなど）を使用してください。

5. **イベント**の下で、このWebhookで受信したいイベントをクリックします。全22イベントは[22種類のWebhookイベント](#the-22-webhook-events)に記載されています。
6. *(オプション)* 一時的な失敗時に <span data-t="appName">Your AI Connector</span> に再試行させたい場合は、**失敗した配信を再試行する**をオンにします。[失敗した配信の再試行](#retrying-failed-deliveries)を参照してください。
7. **Webhookを作成**をクリックします。フォームの下のリストに表示され、いつでも行にある **テスト** をクリックして、エンドポイントにサンプルペイロードを送信できます。

> **権限が必要です。** Webhookの追加、編集、テストには、Integrationsの「編集」権限が必要です（閲覧のみのチームメンバーには、フォームの代わりに読み取り専用の通知が表示されます）。

> **Webhookの署名**を行うには、まずWebhookが保存されている必要があります。既存のWebhookの行を開いて編集すると、編集フォームの下部に**署名シークレット**パネルが表示されます。作成したばかりの未保存のドラフトには、まだ署名オプションはありません。詳細は以下の[署名付きペイロード](#signed-payloads-verifying-a-webhook-really-came-from-us)を参照してください。

---

## すべてのクライアントアカウントに対して1つのWebhookを使用する（代理店向け）

代理店を運営している場合、すべてのクライアントアカウントで同じWebhookを再作成する必要はありません。代理店アカウントのWebhookフォームには、**すべてのクライアントアカウントに対しても実行する**という追加のトグルがあります。これをオンにすると、このWebhookは代理店配下のすべてのクライアントアカウントで発生したイベントも受信するようになります。1つのエンドポイントで、代理店全体をカバーできます。

動作の仕組み：

- **`user`ブロックで、イベントがどのクライアントに属しているかを確認できます。** すべての通知には、イベントが発生したアカウントを識別する`user`ブロックが含まれているため、自動化処理でクライアントごとにルーティングできます。
- **Webhook自体の設定がどこでも適用されます。** 選択したイベント、署名シークレット、および再試行設定は、クライアントアカウントへの配信にも使用されます。
- **重複配信はありません。** クライアントアカウントが同じURLを指す独自のWebhookを持っている場合、そのアカウントのイベントにはそちらが使用されるため、同じイベントが1つのエンドポイントに2回届くことはありません。
- **クライアントには表示されません。** このWebhookはクライアントアカウント自身のWebhookページには表示されず、クライアントがオフにすることもできません。管理はあなたが行います。
- **信頼性はクライアントアカウントごとに追跡されます。** エンドポイントでエラーが続く場合、配信に失敗したアカウントに対してのみ自動的にオフになります（[Webhookの信頼性](#webhook-reliability)を参照）。代理店全体で一度にオフになることはありません。

このトグルは代理店アカウントでのみ表示されます。API経由での設定もサポートされています。[Webhooks API](../api/webhooks.md#one-subscription-for-all-client-accounts-agencies)の`apply_to_sub_accounts`フィールドを参照してください。

---

## 利用可能なトリガーイベント

22種類のWebhookイベントは、それぞれ個別に有効または無効にできます。イベントが発生すると、<span data-t="appName">Your AI Connector</span> は関連データを含む通知をWebhook URLに送信します。各イベントの意味と、ペイロードに含まれる `event` コードについては、このページの下部にある [22種類のWebhookイベント](#the-22-webhook-events) を参照してください。

> **知っておくべきこと:** **タスク作成**、**タスク更新**、**タスク完了**は完全に選択可能で、正しく保存されます。**日次サマリー作成**も最近追加されました。そのペイロードの形式については、以下の[タスク完了Webhook](#task-completed-webhook)を参照してください。

---

## タグベースのWebhookトリガー

`subscribed_to_tags`は、Webhookのイベントをタグにスコープ設定しません。特定のタグが会話サマリー通知を生成するかどうかを絞り込むだけです。特定のタグが適用されたときにリクエストを受け取るには、エージェント（またはキャンペーン）の**タグ**タブで、そのタグにWebhook URLを設定してください。

Webhookフォーム自体には、新規作成時も編集時もタグピッカーがないため、`subscribed_to_tags`は[Webhooks API](../api/webhooks.md)を通じて読み取りや変更を行うか、サポートに問い合わせる必要があります。

> **知っておくべきこと:** `subscribed_to_tags`リストを持つ既存のWebhookを編集（名前の変更、イベントの変更、再試行の切り替え）しても、そのリストがクリアされることはなくなりました。フォームには送信すべきタグピッカーがないため、このページから保存しても既存のリストはそのまま保持されます。（これは**2026年7月21日**以前は実際のバグでした。Webhookフォームから保存すると、常に空のタグリストが送信されるため、リストが消去されていました。その日付より前に`subscribed_to_tags`リストが失われたWebhookは、APIを通じて再設定する必要があります。）

### タグ付けされた連絡先の要約を生成する

Webhookに`subscribed_to_tags`リストがある場合、**サマリーを生成**をオンにできます。有効にすると、<span data-t="appName">Your AI Connector</span>はそれらのタグのいずれかが適用されたときに連絡先の会話サマリーを自動的に生成し、それをWebhookデータに含めます。個別のリクエストなしで完全なコンテキストを取得できます。

---

## Webhookのテスト

1. **設定 → 統合 → Webhooks** を開きます。
2. Webhookの行にある **テスト** をクリックします。
3. 外部システムを確認し、テストデータが受信されたことを確認します。
4. データ形式を確認し、システムで正しく解析できることを確かめます。

完全なエンドツーエンドのテストを行うには、設定したイベント（ブロードキャストや接続済みチャネルへの着信メッセージなど）をトリガーするメッセージを送信し、実際のデータでWebhookが実行されることを確認してください。

::: tip
**ヒント:** 開発中は [webhook.site](https://webhook.site) や [RequestBin](https://requestbin.com) などのツールを使用して、本番システムに接続する前に生のWebhookデータを確認することをお勧めします。
:::


### 配信成功の定義

**Test**をクリックした場合でも、イベントが実際に発生した場合でも、送信される内容は同じです。

- **POST**リクエスト（GETは不可）。ボディはJSON形式で、`Content-Type: application/json`が含まれます。
- [署名付きペイロード](#signed-payloads-verifying-a-webhook-really-came-from-us)に記載されているヘッダー。署名ヘッダーは、署名シークレットを設定した場合にのみ含まれます。

配信が成功したとみなされる条件は以下の通りです。

- エンドポイントが**2xxステータス**（200、201、204など、すべて有効）で応答すること。
- **30秒以内**に応答すること。

意外に思われるかもしれませんが、以下の点にご注意ください。

- **レスポンスボディは無視されます。** 特定のJSONを返す必要はありません。空の200レスポンスで十分です。
- **リダイレクトは失敗とみなされます。** 当社ではリダイレクトを追跡しないため、301や302（末尾のスラッシュによるリダイレクトやhttpからhttpsへのリダイレクトを含む）は配信失敗として記録されます。リダイレクト先ではなく、最終的なURLを保存してください。
- **クエリ文字列は完全にサポートされています。** `https://your-app.com/hook?token=abc123` は保存した通りに送信されるため、パスにトークンを含めるのと同様に、クエリ文字列にトークンを含めても機能します。
- **URLは `https://` であり、公開アクセス可能である必要があります。** <span data-t="appName">Your AI Connector</span> 自体のインフラストラクチャに属するアドレスは拒否されますが、Google Cloud Functions、Cloud Run、App Engine、Firebase Hostingなど、その他の場所にある独自のエンドポイントは問題ありません。
- **エンドポイントの前段にあるファイアウォールやボット保護層によって、リクエストがブロックされる可能性があります。** 最も一般的なケースはCloudflareです。ゾーンで「Bot Fight Mode」や管理されたチャレンジが有効になっていると、サーバーに到達する代わりに「Just a moment...」というチャレンジページが403エラーで返されます。サーバー間リクエストではブラウザのチャレンジを通過できないため、**テスト**ボタンと実際のイベントの両方が同様に失敗します。テストボタンを使用すると、この状況が発生している場合に「Cloudflare is showing a bot challenge to our request（Cloudflareがリクエストに対してボットチャレンジを表示しています）」と通知されます。Cloudflareのセキュリティ/WAFルールで、Webhookパス（または `Webhook-Delivery/1.0` ユーザーエージェント）に対するチャレンジをスキップするように設定し、再度**テスト**をクリックしてください。
- **ファイアウォールでIP許可リストが必要な場合**（Cloudflareの無料プランなど、通常のBot Fight ModeをWAFルールでスキップできず、許可設定されたIPアクセスルールが優先される場合）、当社がサポートいたします。**テスト**ボタンからの配信であれライブイベントからの配信であれ、すべての配信は1つの固定IPv4アドレスから送信されます（範囲指定やIPv6、ローテーションはありません）。サポートまでご連絡いただければ、許可リストに登録するアドレスをお伝えします。送信元に関係なくすべてのペイロードを検証できるため、実際の信頼性チェックには[署名検証](#signed-payloads-verifying-a-webhook-really-came-from-us)を引き続き使用してください。
- **テスト結果には、エンドポイントが回答した内容が正確に表示されます。** テストが失敗した場合、一般的なエラーではなく、実際の理由（エンドポイントが返したHTTPステータス、タイムアウト、またはアドレスに全く到達できなかったこと）が表示されます。また、保存されたWebhookに対するテストは、署名が有効な場合はライブイベントと全く同様に署名付きで送信されます。

### n8n、Make、またはZapierの使用（「テストURL」と「本番URL」）

自動化プラットフォームでは通常、2つの異なるWebhookアドレスが提供されますが、これが混乱の原因となることがあります。

- **テストURL**（n8nでは `/webhook-test/` が含まれます）。これは、キャンバスをアクティブに監視しており、かつ **Listen for test event**（または **Test workflow**）をクリックした直後にのみデータを受信します。単一のイベントをキャプチャするとリッスンを停止するため、<span data-t="appName">Your AI Connector</span> で **テスト** を連続してクリックしても、最初の1回しかキャプチャされません（リッスンウィンドウがその瞬間にアクティブな場合のみ）。テストするには、まずn8nで **Listen for test event** をクリックしてから、<span data-t="appName">Your AI Connector</span> に戻り、**テスト** を1回クリックしてください。
- **本番URL**（n8nでは `/webhook/` が含まれ、`-test` は含まれません）。ライブイベント用に <span data-t="appName">Your AI Connector</span> に貼り付けるのはこちらです。ワークフローが **アクティブ** に切り替えられた後にのみ機能します。ワークフローがアクティブでない場合、<span data-t="appName">Your AI Connector</span> が正しくデータを送信していても、n8nは「404 / webhook not registered」エラーでリクエストを拒否します。

要約すると、テスト中はテストURLを使用してリッスンを行いますが、Webhookが実際の連絡先で機能し続けるようにするには、**本番URL** を <span data-t="appName">Your AI Connector</span> に保存し、ワークフローが **Active** になっていることを確認してください。

---

## Webhookのデータ形式

Webhookが発生すると、<span data-t="appName">Your AI Connector</span>は構造化データ（JSON）をWebhook URLに送信します。ZapierやMakeのような自動化プラットフォームを使用している場合、データは自動的に解析されます。カスタム統合を構築している場合は、以下に注意してください：

```json
{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}
```

| フィールド | 説明 |
|---|---|
| `event` | 通知をトリガーした正確なイベント文字列（例: `contactCreated`、`booked`）。これはイベントリストに表示される表示ラベルでは**ありません**。各ラベルとそれに対応するコードは [22種類のWebhookイベント](#the-22-webhook-events) に記載されています。 |
| `contact` | イベントに関連する連絡先。連絡先に関連付けられていないイベント（`creditsRecharged`など）の場合は `null` となります。 |
| `campaign` | 連絡先が属するキャンペーン。キャンペーンがない場合は `null` となります。 |
| `agent` | 会話を担当するエージェント。エージェントがいない場合は `null` となります。 |
| `user` | データを所有するアカウントの基本的な識別情報。 |

> **`campaign` または `agent` — 通常はどちらか一方であり、両方ではありません。** アカウントでエージェントを使用している場合、連絡先はキャンペーンではなくエージェントに紐付けられるため、`campaign` は `null` として届き、`agent` が誰が対応したかを示します。キャンペーンベースの古いアカウントではその逆になります。`campaign` が常に存在すると想定せず、入力されている方を読み取ってください。

> **`agent` ブロックは2026年8月15日に導入されました。** これは、会話に関連するイベント（終了したチャット、おやすみモード、再開、アーカイブ解除、AIの一時停止、新規メッセージ、会話の要約、およびタグに設定できるWebhook）において `campaign` と並んで配置され、対応する担当者の `id` と `name` を保持します。担当者が関与していない場合は `null` となります。これは純粋な追加機能であり、すでに受信しているすべてのフィールドに変更はありません。そのため、その日付より前に構築された受信側は、何も更新することなくそのまま動作し続けます。

イベントによっては、独自の追加トップレベルブロックが含まれるものがあります。例えば、**Appointment Booked**（予約完了）は `appointment` ブロックを追加し（[Appointment Booked Webhook](#appointment-booked-webhook) を参照）、**New Message**（新規メッセージ）はテキストを含む完全な `message` ブロックを追加し（[New Message Webhook](#new-message-webhook) を参照）、**Deliveries**（配信）および **Reads**（既読）はメッセージIDとステータスのみを含む短い `message` ブロックを追加します（[Deliveries and Reads Webhook](#deliveries-and-reads-webhook) を参照）。

> **Deliveries（配信）と Reads（既読）は、どのメッセージかを示しますが、内容は示しません。** これらにはメッセージの `id` と `status` を含む `message` ブロックが含まれます。この `id` は [メッセージ送信エンドポイント](../api/messages.md#send-a-message) が返す `messageId` と同じであるため、配信通知や既読通知を送信したメッセージと照合できますが、メッセージ本文は含まれません。**Replies**（返信）には `message` ブロックは一切含まれません。送信または受信された内容が必要な場合は、それらと併せて **New Message**（新規メッセージ）をサブスクライブしてください。

> **レシーバーを作成する前に知っておくべき2つのこと。** `timestamp` フィールドはなく、`data` ラッパーもありません。すべてのブロックは、上記のようにJSONオブジェクトのトップレベルに配置されます。

### 22種類のWebhookイベント

22種類のWebhookイベントと、アプリでチェックを入れる表示ラベル、およびペイロードで送信される `event` コードです。`event` コードは表示ラベルと一致し**ない**短い文字列であるため、ラベルではなくコードに基づいて受信側の処理を構築してください。

| 表示ラベル（アプリ内） | ペイロード内の `event` コード | 意味 |
|---|---|---|
| Contact Created | `contactCreated` | アカウントに新しい連絡先が追加されました（手動、インポート、またはAPI経由）。 |
| Contact Paused | `contact_paused` | 連絡先との会話が一時停止されました（ボットが応答を停止します）。 |
| Contact Resumed | `contact_resumed` | 一時停止されていた連絡先との会話が再開されました。 |
| Contact Do Not Disturb | `contact_do_not_disturb_changed` | 連絡先の「おやすみモード」設定がオンになりました。 |
| Contact Unarchived | `contact_unarchived` | アーカイブされていた連絡先から新しいメッセージが送信され、アクティブな受信トレイに戻りました。 |
| New Message | `new_message` | 任意のチャネルの会話にメッセージが追加されました。連絡先から送信されたメッセージと、AIまたはチームから送信されたメッセージの両方が含まれます。実際のメッセージテキストが含まれる唯一のイベントです（[New Message Webhook](#new-message-webhook) を参照）。 |
| Replies | `replied` | 連絡先がメッセージに返信しました。 |
| Reads | `read` | 連絡先がメッセージを既読にしました（既読通知をサポートするチャネルのみ）。既読になったメッセージのIDが含まれます（[Deliveries and Reads Webhook](#deliveries-and-reads-webhook) を参照）。 |
| Deliveries | `delivered` または `undelivered` | メッセージが連絡先に正常に配信されました（配信失敗時は `undelivered`）。メッセージのIDが含まれます（[Deliveries and Reads Webhook](#deliveries-and-reads-webhook) を参照）。 |
| Human Alerted | `humanAlerted` | AIボットが会話を処理できないと判断し、人間の対応が必要なフラグを立てました。 |
| Chat Concluded | `chat_concluded` | AIボットが会話が終了したと判断しました（予約完了、リードの失格など）。 |
| Appointment Booked | `booked` | 連絡先が予約システムを通じて予約を行いました。 |
| Credits Spent | `creditsSpent` | アカウントからクレジットが消費されました。 |
| Credits Recharged | `creditsRecharged` | 自動リチャージまたは手動購入により、アカウントにクレジットが追加されました。 |
| Low Credit Balance | `lowCreditBalance`（**Test**配信時）、`Low Credit Balance`（実際の配信時） | クレジット残高がアラートしきい値を下回ったことの早期警告です（独自の設定がない限り100クレジット）。サブアカウントが共通のプールから消費するエージェンシー向けです。連絡先ブロックの代わりに `balance`、`threshold`、`account_email` が含まれ、残高が低い間は最大24時間に1回送信され、残高がしきい値を超えるとすぐに再有効化されます。 |
| Task Created | `taskCreated` | タスクが作成されました。 |
| Task Updated | `taskUpdated` | タスクが完了ステージに移動せずに変更されました。 |
| Task Completed | `taskCompleted` | タスクが完了ステージとして設定されたステージに移動しました。 |
| Daily Summary Created | `dailySummaryCreated` | 日次サマリーレポートが生成されました。 |
| Channel Connected | `channelConnected` | **まだ送信されません。選択可能ですが、現在は何も出力されません。これに依存した構築は行わないでください。** メッセージングチャネルの接続が完了した際の通知を想定しています。 |
| Broadcast Started | `broadcastStarted` | ブロードキャストの送信が開始されました（ステータスが「送信中」に変更されます）。開始ごとに1回発生します（一時停止されたブロードキャストの再開時を含む）。連絡先ブロックの代わりに `broadcast` ブロックが含まれます：id、name、channel、status、previous status、ターゲットリスト（`list_id`、`list_name`、`is_smart_list`）、`scheduled_at`、`total_contacts`。 |
| Broadcast Completed | `broadcastCompleted` | ブロードキャストが終了しました（ステータスが「送信済み」または「失敗」に変更されます）。同じ `broadcast` ブロックに加え、`completed_at` および利用可能な場合は `completion_summary`（`total_sent`、`permanently_failed`、`unique_replied`、`failure_rate`、`had_errors`）が含まれます。これら2つを使用して、スマートブロードキャストリストを外部ツールに接続します。 |

以下の2つのコードは、購読対象ではないためリストには表示されません。`contact_tags_updated`は個別のタグに設定されたWebhook URLによって送信され、`summary_generated`はWebhookの`subscribed_to_tags`リスト内のタグに対してチャットサマリーが作成されたときに送信されます。

> **「チャネル接続済み」はまだ送信されません。** イベントリストには表示されますが、現時点では何も発行されません。これに基づいた開発は行わないでください。

タグベースおよびタスクの通知は、それぞれ独自の形式を使用します。[Contact Tags Updated](#contact-tags-updated-webhook) および [Task Completed](#task-completed-webhook) を参照してください。

---

## 連絡先作成Webhook

**連絡先作成**イベントが実行されたとき（手動、インポート、またはAPI経由で新しい連絡先が追加されたとき）に送信されます。

### イベント名

`contactCreated`

### ペイロード形式

```json
{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}
```

| フィールド | 説明 |
|---|---|
| `event` | このイベントでは常に `contactCreated` です。 |
| `contact.id` | 新しい連絡先の一意のID。 |
| `contact.email` / `contact.phone_number` | 連絡先のメールアドレスと電話番号（判明している場合。チャネルによって空の場合があります）。 |
| `contact.first_name` / `contact.last_name` | 連絡先の名前（判明している場合）。 |
| `contact.human_alerted` / `contact.human_alert_reason` | 連絡先が人間の対応を必要とするフラグが立てられているかどうか、およびその理由。 |
| `contact.is_bot_active` | AIボットが現在この連絡先に対してアクティブかどうか。 |
| `contact.ad_referral` | Metaの「Click-to-WhatsApp」広告の属性、または `null` — [Click-to-WhatsApp広告の属性](click-to-whatsapp-attribution.md) を参照してください。 |
| `campaign` | 連絡先が作成されたキャンペーン。キャンペーンがない場合は `null` となります。 |
| `agent` | 連絡先に割り当てられたエージェント。エージェントがいない場合は `null` となります。 |
| `user` | 連絡先を所有するアカウントの基本的な識別情報。 |

> **「テスト」サンプルと実際のイベントは少し異なります。** テストボタンはプレースホルダーデータ（John Doe、サンプルキャンペーン）を送信します。実際の「連絡先作成」イベントには実際の連絡先の詳細が含まれ、チャネルによっては一部のフィールドが空になる場合があります。

---

## New Message Webhook

このWebhookは、任意のチャネルで会話にメッセージが追加されるたびに発生します。連絡先から送信されたメッセージと、AI、チーム、またはキャンペーンから送信されたメッセージの両方が対象です。メッセージテキストが含まれる唯一のWebhookであるため、会話を外部システムにミラーリングしたい場合に使用してください。

### イベント名

`new_message`

### ペイロード形式

```json
{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web"
  }
}
```

| フィールド | 説明 |
|---|---|
| `event` | このイベントでは常に `new_message` です。これは送信された正確な文字列であり、表示ラベル「New Message」ではないことに注意してください。 |
| `contact` | メッセージが属する会話の連絡先です。[Contact Created](#contact-created-webhook) と同じ形式です。 |
| `agent` | 会話を担当するエージェント（`id` および `name`）、またはエージェントが関与していない場合は `null` です。 |
| `user` | 会話を所有するアカウントの基本的な識別情報です。 |
| `message.id` | メッセージの一意のIDです。 |
| `message.body` | メッセージテキストです。添付ファイル（画像、ボイスメモ、ドキュメント）のみを含むメッセージの場合は空になります。 |
| `message.direction` | 連絡先からのメッセージは `inbound`、AIまたはチームが受信トレイから送信したメッセージは `outbound`、キャンペーン、ブロードキャスト、テンプレート送信、またはAPIによって送信されたメッセージは `outbound-api` となります。 |
| `message.status` | メッセージのライフサイクルにおける現在の状態です。受信メッセージは `received`、送信メッセージは `queued` / `sent` / `delivered` / `read` / `failed` / `undelivered` となります。これはメッセージ作成時のステータスであるため、送信メッセージは通常 `queued` または `sent` として到着し、その後 `delivered` に達します。その後の遷移が必要な場合は、**Deliveries**（配信）および **Reads**（既読）イベントを使用してください。これらにはこのブロックと同じ `message.id` が含まれるため、このメッセージへの遷移を照合できます（[Deliveries and Reads Webhook](#deliveries-and-reads-webhook) を参照）。 |
| `message.created_at` | メッセージが作成された日時（UTC、ISO 8601形式）です。 |
| `message.channel` | メッセージが通過したチャネルです（例：`whatsapp`、`whatsapp_web`、`sms`、`instagram`、`messenger`、`telegram`、`email`、または `custom`）。 |

> **このペイロードにはまだ `campaign` ブロックは含まれていません。** New Messageは `contact`、`agent`、`user`、および `message` を送信します。`agent` ブロックは **2026年8月15日** に追加され、会話を担当するエージェントを通知します。キャンペーンのコンテキストも必要な場合は、`contact.id` を使用してAPI経由でコンタクトを検索してください。

> **内部AIレコードはこのWebhookを発生させません。** プラットフォームは実際のメッセージと並行して、会話内に独自の記録（AIのツール呼び出しや内部的なターン記録）を保持します。これらは送信されません。実際に送受信されたメッセージのみが通知されます。

---

## Deliveries and Reads Webhook

これら2つのイベントは、メッセージが <span data-t="appName">Your AI Connector</span> を離れた後に何が起こったかを報告します。**Deliveries**（配信）はメッセージが連絡先に到達したとき（または失敗したとき）に発生し、**Reads**（既読）は既読通知をサポートするチャネルで連絡先がメッセージを開いたときに発生します。

どちらもイベント対象のメッセージIDを含む `message` ブロックを保持しているため、更新内容を送信した正確なメッセージと照合できます。

### イベント名

**Deliveries**（配信）には `delivered` と `undelivered`、**Reads**（既読）には `read` が使用されます。

### ペイロード形式

```json
{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}
```

| フィールド | 説明 |
|---|---|
| `event` | **Deliveries**（配信）の場合は `delivered` または `undelivered`、**Reads**（既読）の場合は `read` です。 |
| `contact` | メッセージの送信先である連絡先です。 |
| `campaign` | 連絡先が属するキャンペーン、または `null` です。 |
| `agent` | 会話を担当するエージェント、または `null` です。 |
| `user` | データを所有するアカウントの基本的な識別情報です。 |
| `message.id` | この更新の対象となるメッセージのIDです。これは [メッセージ送信エンドポイント](../api/messages.md#send-a-message) が `messageId` として返す値と同じであり、[New Message](#new-message-webhook) 通知が保持する `message.id` と同じです。 |
| `message.status` | 新しいステータスです。常に `event`（`delivered`、`undelivered`、または `read`）と同じ文字列になります。 |

> **送信したメッセージと更新を照合する方法。** API経由でメッセージを送信したときに返される `messageId` を保存してください。**Deliveries**（配信）または **Reads**（既読）通知が届いたら、その保存したIDをペイロード内の `message.id` と照合します。それがそのメッセージに対する配信通知または既読通知です。

> **ここにメッセージテキストはありません。** `message` ブロックにはIDとステータスのみが含まれます。本文も必要な場合は [New Message](#new-message-webhook) をサブスクライブしてください。

> **`message` ブロックは、どのメッセージか特定できる場合にのみ存在します。** 保存されたメッセージと関連付けられない稀な更新の場合、ブロックは空で送信されるのではなく完全に除外されます。そのため、`message.id` を読み取る前に `message` が存在することを確認してください。

> **ステータス変更ごとに1つの通知。** 通常、1つの送信メッセージは `delivered` 通知を生成し、既読通知に対応しているチャネルではその後 `read` 通知を生成します。送信に失敗した場合は代わりに `undelivered` が生成されます。

---

## Appointment Booked Webhook

連絡先が予約を入れたときに実行されます。AIが会話中に予約した場合、手動で予約した場合、API経由で予約が入った場合のいずれであっても、同じように実行されます。

### イベント名

`booked`

### ペイロード形式

```json
{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}
```

| フィールド | 説明 |
|---|---|
| `event` | このイベントでは常に`booked`です。 |
| `contact` | 予約した人物。`email`と`phone_number`はチャネルによって空の場合があります。 |
| `appointment.appointment_id` | 予約の一意のID。 |
| `appointment.start_time` / `end_time` | 予約されたスロットの開始と終了（UTC、ISO 8601形式）。 |
| `appointment.status` | 予約の現在のステータス。 |
| `appointment.room_name` | 予約が行われた部屋（使用されている場合）。 |
| `appointment.description` / `summary` | 予約時に取得された自由記述の詳細。 |
| `appointment.google_calendar_event_id` | 同期されたイベントのGoogleカレンダーID。通知が送信される瞬間にカレンダーイベントが作成されるため、予約完了Webhookでは`null`になることがよくあります。必要な場合は少し後に`appointment_id`で予約を再取得してください。Googleカレンダーが接続されていないアカウントでは永続的に`null`となります。 |
| `appointment.event` | 予約されたサービス：名前、スロットの長さ、場所、会議リンク、タイプ。 |

> **このWebhookでは `google_calendar_event_id` が `null` になることがよくありますが、これは正常です。** Googleカレンダーのイベントはこの通知が送信されるのと同時に作成されるため、通常IDはまだ準備できていません。必要な場合は、少し時間を置いてから `appointment_id` で予約を再取得してください。アカウントにGoogleカレンダーが接続されていない場合は永久に `null` のままとなりますので、いつまでも待機しないようにしてください。

> **「テスト」ボタンには `appointment` ブロックは含まれていません。** エンドポイントが応答することを確認するために使用し、完全なペイロードを確認するには実際に予約を1件行ってください。

> **このWebhookが発火しない2つのケース：** 外部カレンダーからインポートされた予定、およびFormitable連携を通じて行われた予約。

---

## コンタクトタグ更新Webhook

コンタクトにタグが**適用**され、そのコンタクトが属するエージェントまたはキャンペーンでそのタグにWebhook URLが設定されている場合に発生します。

### イベント名

`contact_tags_updated`

### トリガー条件

- エージェントまたはキャンペーン（あるいはその両方）が割り当てられているコンタクトにタグが適用された場合。
- 適用されたタグのうち少なくとも1つに、そのエージェントまたはキャンペーンの「タグ」タブでWebhook URLが設定されている場合。

コンタクトが両方（エージェントとキャンペーン）を持っている場合、キャンペーンのタグにWebhook URLが設定されていればそちらが優先されます。設定されていない場合はエージェントのものが使用されます。

異なるWebhook URLを持つ複数のタグが同じ更新で適用された場合、URLごとに1つのリクエストが送信され、それぞれそのURLにマッピングされたタグのみが含まれます。

**タグを削除してもリクエストは送信されません。** 多くのユーザーは、これらのURLを「デポジットの回収」「スロットの予約」「担当者への通知」といったアクションに向けているため、タグがコンタクトから外れた際にそのアクションが再実行されることを防ぐためです。現在、削除は実行されません。同じURLに送信される適用と同時に削除が発生した場合、削除は`removed_tags`に表示されるため、両方の配列を読み取る自動化ツールであれば全体像を把握できます。ただし、削除のみによってリクエストが引き起こされることは決してありません。（**2026年8月12日**に変更。それ以前は、削除でもリクエストが送信されていました。）

### ペイロード形式

```json
{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    }
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}
```

| フィールド | 説明 |
|---|---|
| `event` | このWebhookでは常に `contact_tags_updated` となります。 |
| `contact.id` | タグが変更されたコンタクトの一意のID。 |
| `contact.email` / `contact.phone_number` | コンタクトのメールアドレス/電話番号（判明している場合）。 |
| `contact.first_name` / `contact.last_name` | コンタクトの名前。 |
| `contact.human_alerted` | コンタクトが現在、人間の対応が必要なフラグが立てられているかどうか。 |
| `contact.is_bot_active` | このコンタクトの会話でAIボットが現在アクティブかどうか。 |
| `contact.ad_referral` | コンタクトがMetaのClick-to-WhatsApp (CTWA) 広告または投稿を通じて最初に到達した場合にのみ存在します。それ以外の場合は `null`。 |
| `added_tags` | この更新で適用されたタグ名の配列。空になることはありません。適用がリクエストをトリガーするためです。 |
| `removed_tags` | 同じ更新で削除されたタグ名の配列（存在する場合）。削除のみが行われた場合は何も送信されません。 |
| `agent` | コンタクトの会話を担当するエージェント（`id` および `name`）、または担当者がいない場合は `null`。2026年8月15日に追加されました。 |
| `user` | コンタクトを所有するアカウントの基本的な識別情報。 |

### タグWebhookのテスト

「タグ」タブのWebhook URLフィールドの横には、**テスト**ボタンがあります。このボタンを押すと、サンプルペイロードがそのURLに即座に送信されるため、実際の会話を待たずに自動化ツールがそれを受信できることを確認できます。

このテストでは、上記と同じ`contact_tags_updated`形式が送信されます。テスト対象のタグが`added_tags`に、空の`removed_tags`が使用され、プレースホルダーの連絡先が使われます。自動化ツールがテストで確認する内容は、本番環境で確認するものと同じです。

知っておくべき2つのこと：

- **先にタグを保存してください。** テストは保存された名前でタグを検索するため、作成したばかりのタグや保存されていない名前の変更はまだテストできません。画面上の名前が保存されたものと一致するまで、ボタンはグレーアウトしたままになります。
- **テストの失敗はWebhookのカウントに含まれません。** テストは、[Webhookの信頼性](#webhook-reliability)で説明されているような、繰り返される失敗による自動オフの対象にはなりません。

テストが失敗した場合、エンドポイントがどのような応答を返したか（例：`404`や`500`など）が表示されます。これは通常、誤ったURLや有効になっていないワークフローを特定するのに十分な情報です。

---

## タスク完了Webhook

> **参考情報のみ。** タスクWebhook（データとして）は開発者向けにここに記載されています。**タスク作成**、**タスク更新**、**タスク完了**イベントは、他のイベントと同様にWebhookフォームの標準イベントリストで選択可能です。[利用可能なトリガーイベント](#available-trigger-events)および[22種類のWebhookイベント](#the-22-webhook-events)を参照してください。

このペイロードは、タスクが完了ステージとしてマークされたステージに移行したときに送信されます。完了ステージ以外のステージ間を移動するタスクは、代わりに `taskUpdated` の形式を送信します。

### イベント名

`taskCompleted`

### トリガー条件

- タスクが更新された。
- その `stage` 値が以前の値と比較して変更された。
- 新しいステージが、アカウントのタスクステージ設定で完了ステージとして構成されている。

### ペイロード形式

```json
{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}
```

| フィールド | 説明 |
|---|---|
| `event` | このWebhookでは常に `taskCompleted` となります。タスクが完了ステージに入らずに変更された場合、`taskUpdated` と同じペイロード形式が送信されます。 |
| `contact` | タスクにリンクされている連絡先（存在する場合）。リンクされていない場合は `null`。 |
| `contact.human_alert_reason` | 該当する場合、連絡先に人間の対応が必要なフラグが立てられた理由。 |
| `user` | タスクを所有するアカウントの基本的な識別情報。 |
| `message.id` | タスクの一意のID。 |
| `message.title` / `description` | タスクのタイトルと説明。 |
| `message.type` | タスクタイプ（例: `follow_up`, `call`, `custom`）。 |
| `message.priority` | タスクの優先度 (`low`, `medium`, `high`)。 |
| `message.stage` | タスクが現在存在するステージのID。 |
| `message.due_date` | 設定されている場合、タスクの期限。 |
| `message.source` | タスクの作成元 (`ai`, `manual`, `api`)。 |
| `message.source_detail` | ソースに関する詳細情報。 |
| `message.campaign_id` | リンクされたキャンペーンのID、または `null`。 |
| `message.linked_human_alert` | 該当する場合、リンクされた人間によるアラートのID。 |
| `message.tags` | タスクに適用されたタグ。 |
| `message.notes` | タスクに関する自由形式のメモ。 |

---

## Webhookのオフ（または削除）

すべてのWebhookには、その行にオン/オフのスイッチがあります。**オフ**に切り替えるとイベントの受信は停止しますが、設定した内容（URL、イベント、署名シークレットなど）はすべて保持されます。再度オンに切り替えると、中断したところから再開されます。オフにしていた間に発生したイベントは、後から配信されることはありません。

エンドポイントの再構築中、ノイズの多い統合のデバッグ中、または自動化を一時停止する場合など、一時的に配信を停止したいときに使用してください。

Webhookを**削除**（行のゴミ箱アイコン）すると、署名シークレットを含めて完全に削除されます。配信を停止したいだけの場合は、代わりにオフに切り替えてください。削除は、エンドポイントを完全に終了する場合に使用します。

> **これは、Webhookが自動的にオフになることとは異なります。** 繰り返し失敗したためにWebhookが無効になった場合（[Webhookの信頼性](#webhook-reliability)を参照）、上記のトグルをオンにしてもWebhookは復元されません。エンドポイントを修正したら、Webhookを編集してURLを変更して保存する（URLを変更すると自動的に再有効化されます）、またはAPI経由で[再有効化エンドポイント](../api/webhooks.md)を呼び出してください。サポートにお問い合わせいただければ、こちらで再有効化することも可能です。

---

## 署名付きペイロード（Webhookが確実に当社から送信されたものであることの検証）

Webhook URLを知っている人は誰でも、偽のリクエストを送信する可能性があります。Webhookに基づいて自動的にアクション（請求の更新、CRMレコードの作成など）を行う場合は、**署名**を有効にすることで、各リクエストが確実に当社から送信されたものであることを検証できます。

署名は**オプションであり、デフォルトではオフ**になっています。Webhookごとに、そのWebhookの編集ビュー（保存されたWebhookの行を開く）から有効に切り替えます。

### 署名の有効化

1. Webhookを開きます（設定 → 連携 → Webhook → Webhookの行をクリック）。
2. **署名シークレット**セクションで、**生成**をクリックします。
3. シークレットをコピーし（`whsec_`で始まります）、受信システムに保存します。パスワードのように扱ってください。

いつでも同じパネルから、シークレットの表示、コピー、ローテーション、またはオフへの切り替えを行うことができます。

### 送信される内容

署名が有効になると、Webhookのすべての配信に以下の2つの追加HTTPヘッダーが含まれます：

| ヘッダー | 意味 |
|---|---|
| `X-Webhook-Signature` | `v1=<hex>` 形式の署名。 |
| `X-Webhook-Timestamp` | 送信日時（秒単位のUnixタイムスタンプ）。 |

以下の3つは、署名の有無にかかわらず**すべての**配信に含まれます：

| ヘッダー | 意味 |
|---|---|
| `X-Webhook-Delivery` | このイベントの一意のID。再試行しても変わらないため、重複排除に使用します。 |
| `X-Webhook-Attempt` | 試行回数（`1` が初回）。 |
| `X-Webhook-Event` | イベント名。ボディを読み取らずにルーティングできます。 |

### 検証方法

署名は、署名シークレットをキーとして使用し、文字列`<timestamp>.<raw request body>`をHMAC-SHA256でハッシュ化したものです。

**生のリクエストボディ（受信した正確なバイト列）に対して検証してください。** フレームワークがJSONを解析して再シリアル化してからチェックを行うと、バイト列が変化し、署名が一致しなくなります。

Node.jsの例:

```js
const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}
```

Pythonの例:

```python
import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)
```

> **署名の比較には、タイミング攻撃に強い関数** (`timingSafeEqual` / `compare_digest`) を使用し、`==` は使用しないでください。コストはかからず、巧妙な攻撃を防ぐことができます。

### シークレットのローテーション

**Rotate**（ローテーション）をクリックしてシークレットを置き換えます。切り替えは即座に行われ、次の配信から新しいシークレットのみで署名されます。エンドポイントが稼働中の場合は、新しいシークレットをデプロイするまでの数分間、古いシークレットと新しいシークレットの**両方**を受け入れるようにしてください。

署名をオフにすると、署名ヘッダーが送信されなくなります。

---

## 失敗した配信の再試行

デフォルトでは、失敗した配信は再試行されません。その瞬間にシステムがダウンしていると、そのイベントは取りこぼされます。

Webhookの作成/編集フォームで **Retry failed deliveries**（失敗した配信を再試行）をオンにすると、以下の通り再試行が行われます。

| 試行回数 | タイミング |
|---|---|
| 1 | 即時 |
| 2 | 1分後 |
| 3 | 5分後 |
| 4 | 30分後 |
| 5 | 2時間後 |

これは合計で約 **2時間40分** にわたるため、Webhookはメンテナンス期間や短時間の停止であれば耐えることができます。

**再試行の対象:** 一時的な問題（サーバーが5xxエラーを返す、タイムアウト、接続失敗など）。

**再試行されないケース:** エンドポイント自体がリクエストを拒否した場合（4xxエラーなど）、再試行は行われません。同じリクエストを再送しても、同じ拒否結果になるだけだからです。

**再試行されるイベント：** タグWebhook（`contact_tags_updated`）、3つのタスクイベント、および日次サマリー。それ以外は1回のみ送信されるため、スイッチによる制御は行われません。すべてのイベントに `X-Webhook-Delivery` が含まれているため、1つの重複排除ルールですべてをカバーできます。

> **エンドポイントが冪等（べきとう）である場合にのみ、再試行をオンにしてください。** 再試行を行うと、同じイベントが複数回届く可能性があります。重複を認識するには `X-Webhook-Delivery` ヘッダーを使用してください。これは1つのイベントに対してすべての試行で同じ値が保持されるため、すでに処理済みのIDを安全に無視できます。

再試行は、繰り返し失敗した後の自動停止（[Webhookの信頼性](#webhook-reliability)を参照）と連携し、期待通りの動作をします。失敗カウンターは**配信全体**をカウントし、個々の試行ごとではなく、すべての再試行が使い果たされた後にのみカウントされます。

---

## Webhookの信頼性

- <span data-t="appName">Your AI Connector</span>は安全な接続（HTTPS）経由でWebhookを送信します。指定するWebアドレスがHTTPSを使用していることを確認してください。
- システムがエラーを返した場合、配信は失敗とみなされます。
- イベントの取りこぼしを防ぐため、受信システムの稼働状況を監視してください。
- 重要なワークフローでは、[配信失敗時の再試行](#retrying-failed-deliveries)をオンにし、フォールバックメカニズムの導入も検討してください。

> **Webhookは、繰り返し失敗すると自動的にオフになります。** Webhook URLが繰り返し失敗した場合（連続して約5回、または設定関連のエラーの場合は連続して3回）、<span data-t="appName">Your AI Connector</span>はそのURLへのイベント送信を自動的に停止します。エンドポイントが正常な状態に戻ったら、Webhookを編集してURLを変更して保存する（URLを変更すると自動的に再有効化されます）、またはAPI経由で[再有効化エンドポイント](../api/webhooks.md)を使用してください。同じURLで保存し直すだけでは不十分です。サポートに依頼して再有効化してもらうこともできます。

---

## トラブルシューティング

| 問題 | 解決策 |
|---|---|
| Webhookが実行されない | まず、Webhookが行で**オフ**になっていないか確認してください。次に、正しいイベントが選択されていること、およびURLがインターネットから到達可能であることを確認してください。 |
| テストイベントは機能するが実際のイベントは機能しない | 特定のイベントタイプが有効になっていることを確認してください。タグが適用されたときにリクエストを期待している場合、`subscribed_to_tags`はWebhookのイベントをタグにスコープしないことに注意してください。これは、どのタグが会話サマリー通知を生成するかを絞り込むためのものです。特定のタグが適用されたときにリクエストを取得するには、エージェント（またはキャンペーン）の**タグ**タブでWebhook URLを設定してください。[連絡先タグ更新Webhook](#contact-tags-updated-webhook)を参照してください。 |
| n8n / Make / Zapierに何も届かない | おそらくプラットフォームの**テストURL**を使用しています。これは「テストイベントをリッスン」をクリックした直後の単一イベントのみをリッスンします。ライブイベントの場合は、**本番用URL**を保存し、ワークフローを**アクティブ**に切り替えてください。 |
| 重複したイベントを受信する | 同じURLを指す複数のWebhookがないか確認してください。**失敗した配信を再試行**がオンの場合、エンドポイントがイベントを受け入れたものの時間内に応答できなかった場合に繰り返しが発生することが予想されます。`X-Webhook-Delivery`で重複排除を行ってください。 |
| 署名チェックが常に失敗する | ほとんどの場合、チェック前にボディが再シリアル化されたことが原因です。**生の**リクエストボディに対して検証し、`<timestamp>.<body>`に署名してください。また、最近ローテーションした場合は、現在のシークレットを使用していることを確認してください。 |
| 再試行が行われない | 再試行は、その特定のWebhookで有効にされていない限りオフです。4xx応答は再試行されません。 |
| `campaign`ブロックが常に`null`になる | アカウントがエージェントを使用している場合に予想される動作です。連絡先はキャンペーンではなくエージェントに紐付きます。`agent`ブロックを代わりに読み取ってください。[Webhookデータ形式](#webhook-data-format)を参照してください。 |
| データが空または不正な形式 | 受信システムがJSONを受け入れることを確認してください。サーバーログで解析エラーを確認してください。 |
| Webhook URLがエラーを返す | Postmanや[webhook.site](https://webhook.site)などのツールでURLをテストしてください。 |
| 障害後にWebhookが完全に停止した | 繰り返し失敗すると、Webhookは自動的に無効になります。再保存しても有効にはなりません。エンドポイントを修正してから、サポートに連絡してください。 |
| 保存またはテストで権限エラーが発生する | 統合の「編集」権限が必要です。アカウント所有者に付与を依頼してください。 |
| Webhookの`subscribed_to_tags`リストが空で返される | `subscribed_to_tags`はWebhookのイベントをタグにスコープしません。これは、どのタグが会話サマリー通知を生成するかを絞り込むためのものです。Webhookフォームからの編集では、そのリストはクリアされなくなりました（2026年7月21日に修正済み）。その日付より前にWebhookのリストが失われた場合は、[Webhooks API](../api/webhooks.md)経由で`subscribed_to_tags`を再度設定してください。[タグベースのWebhookトリガー](#tag-based-webhook-triggers)を参照してください。 |

---

## 次のステップ

- [GoHighLevel統合](ghl-integration.md) — Webhookを使用して<span data-t="appName">Your AI Connector</span>とGHLを統合します。
- [APIアクセス](api-access.md) — WebhookとAPIを組み合わせて強力な自動化を実現します。
- [タグを使用した連絡先のラベル付け](../get-started/creating-tags.md) — Webhookをトリガーするタグを設定します。