Webhooks #

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

Webhooksとは？ #

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

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

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

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

Webhookの設定方法 #

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

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

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

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

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

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

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

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

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

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

動作の仕組み：

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

このトグルは代理店アカウントでのみ表示されます。API経由での設定もサポートされています。Webhooks APIのapply_to_sub_accountsフィールドを参照してください。

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

22種類のWebhookイベントは、それぞれ個別に有効または無効にできます。イベントが発生すると、Your AI Connector は関連データを含む通知をWebhook URLに送信します。各イベントの意味と、ペイロードに含まれる event コードについては、このページの下部にある 22種類のWebhookイベント を参照してください。

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

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

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

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

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

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

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

Webhookのテスト #

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

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

配信成功の定義 #

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

• POSTリクエスト（GETは不可）。ボディはJSON形式で、Content-Type: application/jsonが含まれます。
• 署名付きペイロードに記載されているヘッダー。署名ヘッダーは、署名シークレットを設定した場合にのみ含まれます。

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

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

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

• レスポンスボディは無視されます。 特定のJSONを返す必要はありません。空の200レスポンスで十分です。
• リダイレクトは失敗とみなされます。 当社ではリダイレクトを追跡しないため、301や302（末尾のスラッシュによるリダイレクトやhttpからhttpsへのリダイレクトを含む）は配信失敗として記録されます。リダイレクト先ではなく、最終的なURLを保存してください。
• クエリ文字列は完全にサポートされています。 https://your-app.com/hook?token=abc123 は保存した通りに送信されるため、パスにトークンを含めるのと同様に、クエリ文字列にトークンを含めても機能します。
• URLは https:// であり、公開アクセス可能である必要があります。 Your AI Connector 自体のインフラストラクチャに属するアドレスは拒否されますが、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、ローテーションはありません）。サポートまでご連絡いただければ、許可リストに登録するアドレスをお伝えします。送信元に関係なくすべてのペイロードを検証できるため、実際の信頼性チェックには署名検証を引き続き使用してください。
• テスト結果には、エンドポイントが回答した内容が正確に表示されます。 テストが失敗した場合、一般的なエラーではなく、実際の理由（エンドポイントが返したHTTPステータス、タイムアウト、またはアドレスに全く到達できなかったこと）が表示されます。また、保存されたWebhookに対するテストは、署名が有効な場合はライブイベントと全く同様に署名付きで送信されます。

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

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

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

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

Webhookのデータ形式 #

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

{
  "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" }
}

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

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

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

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

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

22種類のWebhookイベント #

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

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

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

タグベースおよびタスクの通知は、それぞれ独自の形式を使用します。Contact Tags Updated および Task Completed を参照してください。

連絡先作成Webhook #

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

イベント名 #

contactCreated

ペイロード形式 #

{
  "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"
  }
}

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

New Message Webhook #

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

イベント名 #

new_message

ペイロード形式 #

{
  "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"
  }
}

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

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

Deliveries and Reads Webhook #

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

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

イベント名 #

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

ペイロード形式 #

{
  "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"
  }
}

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

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

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

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

Appointment Booked Webhook #

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

イベント名 #

booked

ペイロード形式 #

{
  "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"
    }
  }
}

この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日に変更。それ以前は、削除でもリクエストが送信されていました。）

ペイロード形式 #

{
  "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"
  }
}

タグWebhookのテスト #

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

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

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

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

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

タスク完了Webhook #

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

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

イベント名 #

taskCompleted

トリガー条件 #

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

ペイロード形式 #

{
  "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"
  }
}

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

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

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

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

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

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

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

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

署名の有効化 #

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

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

送信される内容 #

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

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

検証方法 #

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

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

Node.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の例:

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（失敗した配信を再試行）をオンにすると、以下の通り再試行が行われます。

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

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

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

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

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

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

Webhookの信頼性 #

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

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

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

次のステップ #

• GoHighLevel統合 — Webhookを使用してYour AI ConnectorとGHLを統合します。
• APIアクセス — WebhookとAPIを組み合わせて強力な自動化を実現します。
• タグを使用した連絡先のラベル付け — Webhookをトリガーするタグを設定します。