Webhooks API
Webhooksを使用すると、新しい連絡先、返信、予約の確定など、何らかのイベントが発生した瞬間にプラットフォームから他のシステムへ通知を送ることができます。このAPIは、どのURLがどのイベントを受け取るかというサブスクリプション自体を管理します。エンドポイントが受け取るペイロードの受信および検証方法については、Webhooksを参照してください。
以下のすべてのパスは、APIベースURLからの相対パスです。
https://api.youraiconnector.com/v1
すべてのリクエストは認証されている必要があります。受け入れられる4つの認証方法については、Authenticationを参照してください。ここでの例では X-API-Key ヘッダー(およびcURL用のクエリパラメータ形式)を使用しています。
注: Webhook をアカウントで有効にする必要があります。有効になっていない場合、これらのエンドポイントは 403 を返します。
サブスクリプションの指定方法
各サブスクリプションには id とオプションの name があります。更新、削除、テスト、ヘルスチェック、再有効化のパスでは、どちらも {webhookId} として使用できます。
名前の使用を推奨します。 サブスクリプションIDは位置に依存するため、他のサブスクリプションが削除されるとIDがずれる可能性があります。サブスクリプション作成時に安定した
nameを設定しておけば、名前で指定することで予期せぬ問題を回避できます。
サブスクリプションの一覧取得
GET /webhooks
cURL
curl "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.get(
"https://api.youraiconnector.com/v1/webhooks",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
レスポンス
{
"success": true,
"webhooks": [
{
"id": "0",
"name": "Order updates hook",
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"subscribed_to_tags": [],
"created_at": "2026-06-09T12:00:00.000Z",
"signing_enabled": true,
"signing_secret_created_at": "2026-07-15T09:30:00.000Z",
"retries_enabled": true,
"enabled": true,
"apply_to_sub_accounts": false
}
]
}
signing_enabled と retries_enabled はサブスクリプションごとのオプトイン設定であり、有効にしない限り両方ともオフになっています。署名付きペイロード および 再試行 を参照してください。
apply_to_sub_accounts は代理店継承のオプトインです。詳細は すべてのクライアントアカウントを1つのサブスクリプションで管理する を参照してください。デフォルトではオフになっており、クライアントアカウントを持たないアカウントでは無効です。
enabled はサブスクリプションのオン/オフスイッチです。サブスクリプションをオフにする を参照してください。オフにされたサブスクリプションも引き続きここに一覧表示されます。
署名シークレット自体はここには含まれません。 GET /webhooks/{id}/signing-secret から読み取ってください。
サブスクライブ可能なイベントタイプの一覧取得
subscribed_to で使用できる正確な文字列を返します。有効なイベント名をハードコーディングするのではなく、これを使用して確認してください。
GET /webhooks/events
cURL
curl "https://api.youraiconnector.com/v1/webhooks/events" \
-H "X-API-Key: YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/events", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.get(
"https://api.youraiconnector.com/v1/webhooks/events",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
レスポンス
レスポンスは {"success": true, "events": [...]} であり、events には現在、以下の22個の正確な文字列が保持されています:Contact Created、Human Alerted、Appointment Booked、Replies、Reads、Deliveries、Credits Spent、Credits Recharged、Low Credit Balance、Contact Paused、Contact Do Not Disturb、Contact Unarchived、New Message、Contact Resumed、Chat Concluded、Task Created、Task Updated、Task Completed、Daily Summary Created、Channel Connected、Broadcast Started、および Broadcast Completed(Channel Connected は subscribed_to で受け入れられますが、現在それを発行するものはないため、これに依存した構築は行わないでください)。
各イベントの意味と、ペイロードで送信される event コードについては、22種類のWebhookイベント を参照してください。このエンドポイントは常に最新のリストを提供します。名前をハードコーディングするのではなく、ライブで読み取ってください。
サブスクリプションの作成
POST /webhooks
| フィールド | 必須 | 説明 |
|---|---|---|
url |
はい | POST 経由でイベントペイロードを受信するHTTPS URL。パブリックにアクセス可能である必要があります。 |
subscribed_to |
はい | イベント名の空ではない配列(/webhooks/events を参照)。 |
name |
いいえ | 表示名。後で {webhookId} として使用することも可能です。デフォルトはタイムスタンプ付きの名前です。 |
subscribed_to_tags |
いいえ | 会話サマリー通知を生成するタグを絞り込むためのタグID。これはサブスクリプションのイベントをそれらのタグに限定するものではありません。特定のタグが適用されたときにリクエストを受け取るには、エージェント(またはキャンペーン)の タグ タブでそのタグにWebhook URLを設定してください。 |
retries_enabled |
いいえ | ブール値、デフォルトは false。失敗した配信の 再試行 をオプトインします。 |
generate_signing_secret |
いいえ | ブール値、デフォルトは false。サブスクリプションと共にHMAC 署名シークレット を生成します。シークレットはレスポンスのトップレベルの signing_secret として一度だけ返されます。 |
enabled |
いいえ | ブール値、デフォルトは true。false を渡すと、サブスクリプションをオフの状態で作成します。サブスクリプションをオフにする を参照してください。 |
apply_to_sub_accounts |
いいえ | ブール値、デフォルトは false。代理店アカウントの場合、true を設定すると、このサブスクリプションですべてのクライアントアカウントのイベントも受信するようになります。すべてのクライアントアカウントを1つのサブスクリプションで管理する を参照してください。 |
URLのルール: URLは
https://を使用し、パブリックにアクセス可能である必要があります。プレーンなhttp://、localhost、プライベートネットワークアドレス、およびプラットフォーム内部のアドレスは、400を伴って拒否されます。
cURL
curl -X POST "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Order updates hook"
}'
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://hooks.example.com/incoming",
subscribed_to: ["Contact Created", "Replies"],
name: "Order updates hook",
}),
});
const data = await res.json();
Python
import requests
res = requests.post(
"https://api.youraiconnector.com/v1/webhooks",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Order updates hook",
},
)
data = res.json()
レスポンス
{
"success": true,
"webhook_id": "1",
"webhook": {
"id": "1",
"name": "Order updates hook",
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"subscribed_to_tags": [],
"created_at": "2026-06-09T12:00:00.000Z"
}
}
サブスクリプションの更新
url、subscribed_to、name、subscribed_to_tags、retries_enabled、enabled、または apply_to_sub_accounts のいずれか少なくとも1つを指定してください。省略されたフィールドは現在の値を保持します。subscribed_to と subscribed_to_tags はマージではなく置換されます。
PUT /webhooks/{webhookId}
サブスクリプションを更新しても署名シークレットは変更されません。管理は 署名シークレットルート を通じて行ってください。
URLが変更されると、新しいURLへの配信が自動的に再有効化され、以前に失敗していたエンドポイントに新たなスタートが与えられます。
cURL
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/Order%20updates%20hook" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/v2/incoming",
"subscribed_to": ["Replies", "Chat Concluded"]
}'
JavaScript
const res = await fetch(
`https://api.youraiconnector.com/v1/webhooks/${encodeURIComponent("Order updates hook")}`,
{
method: "PUT",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://hooks.example.com/v2/incoming",
subscribed_to: ["Replies", "Chat Concluded"],
}),
}
);
const data = await res.json();
Python
import requests
res = requests.put(
"https://api.youraiconnector.com/v1/webhooks/Order updates hook",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"url": "https://hooks.example.com/v2/incoming",
"subscribed_to": ["Replies", "Chat Concluded"],
},
)
data = res.json()
レスポンス
{
"success": true,
"webhook_id": "0",
"webhook": {
"id": "0",
"name": "Order updates hook",
"url": "https://hooks.example.com/v2/incoming",
"subscribed_to": ["Replies", "Chat Concluded"],
"subscribed_to_tags": [],
"created_at": "2026-06-09T12:00:00.000Z"
}
}
不明なIDまたは名前を指定すると、{ "success": false, "error": "Webhook not found" } を伴う 404 が返されます。
サブスクリプションの削除
サブスクリプションを削除し、そのURLがペイロードを受信しないようにします。配信健全性カウンターがリセットされるため、後で同じURLを再追加した場合はクリーンな記録から開始されます。
DELETE /webhooks/{webhookId}
cURL
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0" \
-H "X-API-Key: YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0", {
method: "DELETE",
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.delete(
"https://api.youraiconnector.com/v1/webhooks/0",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
レスポンス
{
"success": true
}
テストペイロードの送信
サブスクリプションのURLにサンプルペイロードを送信し、受信側でエンドツーエンドの検証を行えるようにします。オプションで event を渡すことで、シミュレートするイベントタイプを制御できます。テスト配信は、サブスクリプションの健全性カウンターには一切影響しません。
POST /webhooks/{webhookId}/test
レスポンスは常に 200 を返し、delivered フラグで結果を報告します。テストが失敗してもエラー状態は返されません。delivered が false の場合、レスポンスには失敗の詳細が含まれます。
| フィールド | 必須 | 説明 |
|---|---|---|
event |
いいえ | シミュレートするイベントタイプ(/webhooks/events のいずれかである必要があります)。デフォルトは配信イベントです。 |
cURL
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/test?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "event": "Contact Created" }'
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/test", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ event: "Contact Created" }),
});
const data = await res.json();
Python
import requests
res = requests.post(
"https://api.youraiconnector.com/v1/webhooks/0/test",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"event": "Contact Created"},
)
data = res.json()
レスポンス (配信済み)
{
"success": true,
"webhook_id": "0",
"delivered": true
}
レスポンス (失敗)
{
"success": true,
"webhook_id": "0",
"delivered": false,
"failure_type": "permanent",
"status_code": 404,
"error_message": "Request failed with status code 404"
}
failure_type は permanent、temporary、timeout、network、または unknown のいずれかです。
配信の健全性を確認する
サブスクリプションのURLに対する配信健全性レコードを返します。これには、配信の成功数と失敗数、繰り返される失敗により現在配信が一時停止されているかどうか、および直近の失敗の詳細が含まれます。まだ配信が試行されていない場合は "health": null を返します。
GET /webhooks/{webhookId}/health
cURL
curl "https://api.youraiconnector.com/v1/webhooks/0/health" \
-H "X-API-Key: YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/health", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.get(
"https://api.youraiconnector.com/v1/webhooks/0/health",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
レスポンス
{
"success": true,
"webhook_id": "0",
"url": "https://hooks.example.com/incoming",
"health": {
"consecutive_failures": 0,
"total_failures": 2,
"total_successes": 120,
"is_disabled": false,
"disabled_at": null,
"disabled_reason": null,
"last_failure": null,
"last_success_at": "2026-06-09T12:00:00.000Z",
"created_at": "2026-05-01T08:00:00.000Z",
"updated_at": "2026-06-09T12:00:00.000Z"
}
}
is_disabled が true の場合、繰り返される失敗により、そのURLへの配信は自動的に一時停止されています。受信側を修正してから、(以下で)再有効化してください。
配信を再有効化する
繰り返される失敗により自動的に一時停止されたWebhookの配信を再開します。これにより、一時停止フラグと失敗カウンターがリセットされますが、配信の再試行は行われません。受信側が正常に戻ったことを確認するには、その後にテストエンドポイントを使用してください。
POST /webhooks/{webhookId}/reenable
cURL
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/reenable?apiKey=YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/reenable", {
method: "POST",
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.post(
"https://api.youraiconnector.com/v1/webhooks/0/reenable",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
レスポンス
{
"success": true,
"webhook_id": "0"
}
サブスクリプションをオフにする
enabled はサブスクリプション自体のオン/オフスイッチです。オフにすると、URL、イベントリスト、署名シークレットを保持したまま配信が停止されます。
# Off
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'
# Back on
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
- 指定がない場合はオンになります。 このフィールドが存在する前に作成されたサブスクリプションには
enabledの値が保存されておらず、通常通り配信されます。GET /webhooksは常に具体的なブール値を報告します。 - オフにされたサブスクリプションも
GET /webhooksによって引き続き一覧表示されます。これが、再度オンにするためにサブスクリプションを見つける方法です。 - スイッチをオフにする前にキューに入れられた 再試行 は再開されません。再試行は送信時にサブスクリプションを再読み込みし、オフになっている場合は破棄されます。
- オフにしている間に抑制されたものは、再度オンにしても再送(リプレイ)されません。
繰り返し失敗した後の自動無効化とは異なります。自動無効化は
GET /webhooks/{id}/healthによってis_disabledとして報告され、POST /webhooks/{id}/reenableでクリアされます。enabledはアカウントのスイッチであり、is_disabledは当社のスイッチです。一方が他方を上書きすることはありません。配信を行うには、サブスクリプションがオンになっており、かつ自動無効化されていない状態である必要があります。
すべてのクライアントアカウントを1つのサブスクリプションで管理する(代理店向け)
代理店アカウントでは、サブスクリプション作成時または PUT 経由で apply_to_sub_accounts: true を設定すると、代理店のすべてのクライアントアカウントで発生したイベントも受信するようになります。クライアントアカウントごとにサブスクリプションを再作成する代わりに、1つのエンドポイントで代理店全体をカバーできます。
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"apply_to_sub_accounts": true}'
動作の仕組み:
userブロックでアカウントを識別します。 すべてのペイロードのuserブロックは、イベントが実際に発生したアカウントを特定するため、受信側でクライアントごとにルーティングできます。- 代理店サブスクリプション独自の設定がどこでも適用されます。 イベントリスト、署名シークレット、および 再試行 のオプトイン設定は、継承された配信にも使用されます。
- 同じURLに対するクライアントアカウント独自のサブスクリプションが優先されます。 クライアントアカウントが同じURLを指す独自のサブスクリプションを持っている場合、そのアカウントのイベントにはそちらが使用されます。同じイベントが1つのエンドポイントに2回配信されることはありません。
- クライアントアカウントには表示されません。 継承されたサブスクリプションはクライアントアカウント自身のWebhookリストには表示されず、クライアントがそれらをオフにすることもできません。管理は代理店のみが行います。
- 配信の健全性はクライアントアカウントごとに追跡されます。 配信失敗が続くエンドポイントは、代理店全体ではなく、配信に失敗したアカウントに対して自動的に無効化されます。
subscribed_to_tagsは継承されません。 タグリストは代理店自身のタグを参照しますが、これらはクライアントアカウントには存在しないため、会話サマリーの絞り込みは代理店自身のイベントにのみ適用されます。- それ以外では無効です。 クライアントアカウントを持たないアカウントでは、このフラグは保存されますが何も機能しません。
すべての配信に含まれるヘッダー
これら3つのヘッダーは、サブスクリプションが署名されているかどうかにかかわらず、すべての配信で送信されます:
| ヘッダー | 意味 |
|---|---|
X-Webhook-Delivery |
論理イベントの安定したID。再試行間で同一であるため、これを使用して重複排除を行ってください。 |
X-Webhook-Attempt |
1から始まる試行回数。 |
X-Webhook-Event |
イベント名。 |
署名付きペイロード
署名はオプションであり、デフォルトではオフになっています。サブスクリプションごとに設定されます。サブスクリプションに署名シークレットがある場合、すべての配信で送信される3つのヘッダー(X-Webhook-Delivery、X-Webhook-Attempt、X-Webhook-Event)に加えて、さらに2つのヘッダーが送信されます:
| ヘッダー | 意味 |
|---|---|
X-Webhook-Signature |
v1=<hex> — GET/POST/DELETE /v1/webhooks/{webhookId}/signing-secret で作成およびローテーションするWebhookごとの署名シークレットをキーとして使用した、文字列 "<timestamp>.<raw request body>" のHMAC-SHA256。 |
X-Webhook-Timestamp |
送信時刻(Unix秒)。署名に組み込まれているため、独立して変更することはできません。 |
検証するには、シークレットを使用して生のボディに対してHMAC-SHA256を再計算し、ヘッダーと比較します。生のリクエストボディに対して検証を行ってください。解析されたJSONを再シリアル化するとバイトが変化し、比較が失敗します。リプレイ攻撃を防ぐため、タイムスタンプが鮮度ウィンドウ(デフォルトでは300秒が妥当)の外にある配信は拒否し、タイミング攻撃に強い関数を使用して比較してください。
NodeおよびPythonでの完全な検証例については、署名付きペイロード を参照してください。
署名はAPI認証とは異なります。 REST API自体はOAuthではなくAPIキーで認証されます(ボットツールとして登録するMCPサーバーにはOAuth 2.1が存在します)。また、公式のnpmやPyPI SDKパッケージはまだ存在しないため、任意のHTTPクライアントでエンドポイントを呼び出してください。
署名シークレットの読み取り
GET /webhooks/{id}/signing-secret
curl "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
レスポンス
{
"success": true,
"webhook_id": "0",
"signing_enabled": true,
"signing_secret": "whsec_1a2b3c...",
"signing_secret_created_at": "2026-07-15T09:30:00.000Z"
}
署名が無効な場合、signing_enabled は false であり、signing_secret は null です。
署名シークレットの生成またはローテーション
POST /webhooks/{id}/signing-secret
シークレットを作成(署名を有効化)するか、既存のシークレットを置き換えます。新しいシークレットを返します。
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
レスポンス
{
"success": true,
"webhook_id": "0",
"signing_enabled": true,
"signing_secret": "whsec_9f8e7d...",
"signing_secret_created_at": "2026-07-15T10:00:00.000Z"
}
ローテーションは即座に有効になります。次回の配信からは新しいシークレットのみで署名されます。ライブエンドポイントへの変更を展開する間は、一時的に両方のシークレットを受け入れるようにしてください。
POST /webhooks に "generate_signing_secret": true を渡すことで、作成時にシークレットを生成することもできます。その場合、レスポンスにはトップレベルの signing_secret フィールドが含まれます。
署名を無効化する
DELETE /webhooks/{id}/signing-secret
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
レスポンス
{
"success": true,
"webhook_id": "0",
"signing_enabled": false
}
3つの署名シークレットルートすべてにおいて、
GETを含め、インテグレーションの 編集 権限が必要です。シークレットは配信を偽造できる認証情報であるため、読み取り専用のロールには公開されません。
再試行
オプションであり、デフォルトではオフになっています。POST /webhooks または PUT /webhooks/{id} の retries_enabled ブール値を使用して、サブスクリプションごとに設定します。
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"retries_enabled": true}'
有効にすると、配信に失敗した場合、最初の試行から 1分後、5分後、30分後、2時間後 に再試行が行われます(合計で約2時間40分のカバー範囲)。
- 再試行対象: 5xxレスポンス、タイムアウト、接続失敗。
- 再試行対象外: すべての4xx。受信側がリクエスト自体を拒否しているため、変更せずに再送しても拒否が繰り返されるだけです。
再試行により、イベントが重複して配信される可能性があります。イベントを処理したものの、応答前にタイムアウトが発生したエンドポイントには、再度同じイベントが送信されます。試行間で不変である X-Webhook-Delivery を使用して重複排除を行ってください。これが、再試行がオプトイン方式である理由です。
delivery-health カウンターは、試行ごとではなく、配信全体をカウントします。失敗はすべての再試行が終了した後にのみ記録されるため、再試行を有効にしても自動無効化トリガーが早く作動することはありません。
エラー
すべてのエラーは標準のエンベロープを使用します:
{
"success": false,
"error": "Webhook not found"
}
一般的なケース:許可されていないURL、空または無効な subscribed_to、あるいは不足しているフィールドは 400 を返します。不明なIDまたは名前は 404 を返します。また、403 はアカウントでWebhookが有効になっていないことを意味します。完全なリストについては エラー を参照してください。
次のステップ
- Webhooks (ペイロードの受信) — 受信側の設定とペイロードの形式について説明します。
- 認証 — リクエストを認証する4つの方法について説明します。
- エラーとレート制限 — ステータスコードと300リクエスト/分の制限について説明します。