# Webhooks API

Webhooksを使用すると、新しい連絡先、返信、予約の確定など、何らかのイベントが発生した瞬間にプラットフォームから他のシステムへ通知を送ることができます。このAPIは、どのURLがどのイベントを受け取るかという**サブスクリプション**自体を管理します。エンドポイントが受け取るペイロードの受信および検証方法については、[Webhooks](../integrations/webhooks.md)を参照してください。

以下のすべてのパスは、APIベースURLからの相対パスです。

```
https://api.youraiconnector.com/v1
```

すべてのリクエストは認証されている必要があります。受け入れられる4つの認証方法については、[Authentication](authentication.md)を参照してください。ここでの例では `X-API-Key` ヘッダー（およびcURL用のクエリパラメータ形式）を使用しています。

::: note
**注:** Webhook をアカウントで有効にする必要があります。有効になっていない場合、これらのエンドポイントは `403` を返します。
:::


---

## サブスクリプションの指定方法

各サブスクリプションには `id` とオプションの `name` があります。更新、削除、テスト、ヘルスチェック、再有効化のパスでは、どちらも `{webhookId}` として使用できます。

> **名前の使用を推奨します。** サブスクリプションIDは位置に依存するため、他のサブスクリプションが削除されるとIDがずれる可能性があります。サブスクリプション作成時に安定した `name` を設定しておけば、名前で指定することで予期せぬ問題を回避できます。

---

## サブスクリプションの一覧取得

`GET /webhooks`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**レスポンス**

```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` はサブスクリプションごとのオプトイン設定であり、有効にしない限り両方ともオフになっています。[署名付きペイロード](#signed-payloads) および [再試行](#retries) を参照してください。

`apply_to_sub_accounts` は代理店継承のオプトインです。詳細は [すべてのクライアントアカウントを1つのサブスクリプションで管理する](#one-subscription-for-all-client-accounts-agencies) を参照してください。デフォルトではオフになっており、クライアントアカウントを持たないアカウントでは無効です。

`enabled` はサブスクリプションのオン/オフスイッチです。[サブスクリプションをオフにする](#switching-a-subscription-off) を参照してください。オフにされたサブスクリプションも引き続きここに一覧表示されます。

署名シークレット自体はここには含まれません。 [`GET /webhooks/{id}/signing-secret`](#read-the-signing-secret) から読み取ってください。

---

## サブスクライブ可能なイベントタイプの一覧取得

`subscribed_to` で使用できる正確な文字列を返します。有効なイベント名をハードコーディングするのではなく、これを使用して確認してください。

`GET /webhooks/events`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks/events" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```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**

```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イベント](../integrations/webhooks.md#the-22-webhook-events) を参照してください。このエンドポイントは常に最新のリストを提供します。名前をハードコーディングするのではなく、ライブで読み取ってください。

---

## サブスクリプションの作成

`POST /webhooks`

| フィールド | 必須 | 説明 |
|---|---|---|
| `url` | はい | `POST` 経由でイベントペイロードを受信するHTTPS URL。パブリックにアクセス可能である必要があります。 |
| `subscribed_to` | はい | イベント名の空ではない配列（`/webhooks/events` を参照）。 |
| `name` | いいえ | 表示名。後で `{webhookId}` として使用することも可能です。デフォルトはタイムスタンプ付きの名前です。 |
| `subscribed_to_tags` | いいえ | 会話サマリー通知を生成するタグを絞り込むためのタグID。これはサブスクリプションのイベントをそれらのタグに限定するものではありません。特定のタグが適用されたときにリクエストを受け取るには、エージェント（またはキャンペーン）の **タグ** タブでそのタグにWebhook URLを設定してください。 |
| `retries_enabled` | いいえ | ブール値、デフォルトは `false`。失敗した配信の [再試行](#retries) をオプトインします。 |
| `generate_signing_secret` | いいえ | ブール値、デフォルトは `false`。サブスクリプションと共にHMAC [署名シークレット](#signed-payloads) を生成します。シークレットはレスポンスのトップレベルの `signing_secret` として一度だけ返されます。 |
| `enabled` | いいえ | ブール値、デフォルトは `true`。`false` を渡すと、サブスクリプションをオフの状態で作成します。[サブスクリプションをオフにする](#switching-a-subscription-off) を参照してください。 |
| `apply_to_sub_accounts` | いいえ | ブール値、デフォルトは `false`。代理店アカウントの場合、`true` を設定すると、このサブスクリプションですべてのクライアントアカウントのイベントも受信するようになります。[すべてのクライアントアカウントを1つのサブスクリプションで管理する](#one-subscription-for-all-client-accounts-agencies) を参照してください。 |

> **URLのルール:** URLは `https://` を使用し、パブリックにアクセス可能である必要があります。プレーンな `http://`、`localhost`、プライベートネットワークアドレス、およびプラットフォーム内部のアドレスは、`400` を伴って拒否されます。

**cURL**

```bash
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**

```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**

```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()
```

**レスポンス**

```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}`

> サブスクリプションを更新しても署名シークレットは変更されません。管理は [署名シークレットルート](#signed-payloads) を通じて行ってください。

> URLが変更されると、新しいURLへの配信が自動的に再有効化され、以前に失敗していたエンドポイントに新たなスタートが与えられます。

**cURL**

```bash
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**

```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**

```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()
```

**レスポンス**

```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**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```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**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/webhooks/0",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true
}
```

---

## テストペイロードの送信

サブスクリプションのURLにサンプルペイロードを送信し、受信側でエンドツーエンドの検証を行えるようにします。オプションで `event` を渡すことで、シミュレートするイベントタイプを制御できます。テスト配信は、サブスクリプションの健全性カウンターには一切影響しません。

`POST /webhooks/{webhookId}/test`

レスポンスは常に `200` を返し、`delivered` フラグで結果を報告します。テストが失敗してもエラー状態は返されません。`delivered` が `false` の場合、レスポンスには失敗の詳細が含まれます。

| フィールド | 必須 | 説明 |
|---|---|---|
| `event` | いいえ | シミュレートするイベントタイプ（`/webhooks/events` のいずれかである必要があります）。デフォルトは配信イベントです。 |

**cURL**

```bash
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**

```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**

```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()
```

**レスポンス** (配信済み)

```json
{
  "success": true,
  "webhook_id": "0",
  "delivered": true
}
```

**レスポンス** (失敗)

```json
{
  "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**

```bash
curl "https://api.youraiconnector.com/v1/webhooks/0/health" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```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**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/0/health",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**レスポンス**

```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**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/reenable?apiKey=YOUR_API_KEY"
```

**JavaScript**

```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**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/reenable",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "webhook_id": "0"
}
```

---

## サブスクリプションをオフにする

`enabled` はサブスクリプション自体のオン/オフスイッチです。オフにすると、URL、イベントリスト、署名シークレットを保持したまま配信が停止されます。

```bash
# 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` によって**引き続き一覧表示されます**。これが、再度オンにするためにサブスクリプションを見つける方法です。
- スイッチをオフにする前にキューに入れられた [再試行](#retries) は再開されません。再試行は送信時にサブスクリプションを再読み込みし、オフになっている場合は破棄されます。
- オフにしている間に抑制されたものは、再度オンにしても再送（リプレイ）されません。

> 繰り返し失敗した後の自動無効化とは異なります。自動無効化は [`GET /webhooks/{id}/health`](#check-delivery-health) によって `is_disabled` として報告され、[`POST /webhooks/{id}/reenable`](#re-enable-delivery) でクリアされます。`enabled` はアカウントのスイッチであり、`is_disabled` は当社のスイッチです。一方が他方を上書きすることはありません。配信を行うには、サブスクリプションがオンになっており、かつ自動無効化されていない状態である必要があります。

---

## すべてのクライアントアカウントを1つのサブスクリプションで管理する（代理店向け）

代理店アカウントでは、サブスクリプション作成時または `PUT` 経由で `apply_to_sub_accounts: true` を設定すると、代理店のすべてのクライアントアカウントで発生したイベントも受信するようになります。クライアントアカウントごとにサブスクリプションを再作成する代わりに、1つのエンドポイントで代理店全体をカバーできます。

```bash
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` ブロックは、イベントが実際に発生したアカウントを特定するため、受信側でクライアントごとにルーティングできます。
- **代理店サブスクリプション独自の設定がどこでも適用されます。** イベントリスト、[署名シークレット](#signed-payloads)、および [再試行](#retries) のオプトイン設定は、継承された配信にも使用されます。
- **同じ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での完全な検証例については、[署名付きペイロード](../integrations/webhooks.md#signed-payloads-verifying-a-webhook-really-came-from-us) を参照してください。

> **署名はAPI認証とは異なります。** REST API自体はOAuthではなくAPIキーで認証されます（ボットツールとして登録するMCPサーバーにはOAuth 2.1が存在します）。また、公式のnpmやPyPI SDKパッケージはまだ存在しないため、任意のHTTPクライアントでエンドポイントを呼び出してください。

### 署名シークレットの読み取り

`GET /webhooks/{id}/signing-secret`

```bash
curl "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**レスポンス**

```json
{
  "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`

シークレットを作成（署名を有効化）するか、既存のシークレットを置き換えます。新しいシークレットを返します。

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**レスポンス**

```json
{
  "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`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**レスポンス**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": false
}
```

> 3つの署名シークレットルートすべてにおいて、`GET` を含め、インテグレーションの **編集** 権限が必要です。シークレットは配信を偽造できる認証情報であるため、読み取り専用のロールには公開されません。

---

## 再試行

オプションであり、デフォルトではオフになっています。`POST /webhooks` または `PUT /webhooks/{id}` の `retries_enabled` ブール値を使用して、サブスクリプションごとに設定します。

```bash
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](#check-delivery-health) カウンターは、試行ごとではなく、配信全体をカウントします。失敗はすべての再試行が終了した後にのみ記録されるため、再試行を有効にしても自動無効化トリガーが早く作動することはありません。

---

## エラー

すべてのエラーは標準のエンベロープを使用します：

```json
{
  "success": false,
  "error": "Webhook not found"
}
```

一般的なケース：許可されていないURL、空または無効な `subscribed_to`、あるいは不足しているフィールドは `400` を返します。不明なIDまたは名前は `404` を返します。また、`403` はアカウントでWebhookが有効になっていないことを意味します。完全なリストについては [エラー](errors-and-pagination.md) を参照してください。

---

## 次のステップ

- [Webhooks (ペイロードの受信)](../integrations/webhooks.md) — 受信側の設定とペイロードの形式について説明します。
- [認証](authentication.md) — リクエストを認証する4つの方法について説明します。
- [エラーとレート制限](errors-and-pagination.md) — ステータスコードと300リクエスト/分の制限について説明します。