# ウェブフックエンドポイントを追加する

`POST /v1/webhook-endpoints` · 権限 `webhook-endpoints:write` · すべてのプラン

環境のイベントを受信するエンドポイントを追加します。署名は Standard Webhooks v1 方式で行われます。配信は少なくとも 1 回行われるため、`webhook-id` ヘッダーを使って重複を排除してください。

- **署名シークレット。** レスポンスには `signing_secret`（`idp_whsec_…`）が 1 回だけ含まれ、`Cache-Control: no-store` が設定されます。再度取得することはできないため、直ちに保存してください。同じ `Idempotency-Key` で繰り返されたリクエストは、シークレットを含まず `secret_redacted: true` を付けてエンドポイントを返します。シークレットを紛失または漏えいした場合は [署名シークレットをローテーションする](rotate-secret.md) を使用してください。
- **URL。** `https` のみ使用できます。ポート番号は指定しないか 443 のみ、ユーザー情報やフラグメントは含められず、IP リテラルも使用できません。文字数は最大 2,048 文字です。リダイレクトは追従されません。
- **イベント。** `event_types` にはカタログのイベントタイプを指定します。空のリストの場合は、大量発生型を除くすべてのタイプが対象になります。
- **上限。** 環境で有効にできるエンドポイントは、Free 3、Startup 20、Business 20、Enterprise 50 までです。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `url` | string | はい | 受信先 URL（上記のルール）。 |
| `key` | string | いいえ | 環境内で一意の安定したキー: `[a-z0-9][a-z0-9_-]{0,63}`。既定値は `endpoint-<ID の末尾 8 文字>`。 |
| `description` | string | いいえ | 最大 500 文字。 |
| `event_types` | array | いいえ | カタログのイベントタイプ。最大 100 件、重複不可。空または省略時は、大量発生型を除くすべてのタイプ。 |
| `event_schema_versions` | object | いいえ | イベントタイプからスキーマバージョンへの対応。記載のないタイプは、サポートされている最も古いバージョンで送信されます。 |
| `payload_mode` | string | いいえ | `thin`（既定値: ID、変更されたフィールド名と状態フィールド。個人データは含みません）または `full`（リソースの管理 API 表現）。 |
| `rate_limit_per_second` | integer | いいえ | このエンドポイントへの配信レートの上限（1 秒あたり 1〜1,000 件）。既定値は 50。 |
| `status` | string | いいえ | `enabled`（既定値）または `disabled_by_user`。 |
| `Idempotency-Key` | header | いいえ | 同じキーで繰り返されたリクエストに対し、レスポンス（シークレットを除く）を再送します。 |

```json
{
  "url": "https://hooks.example.com/keenauth",
  "key": "crm-sync",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"]
}
```

## レスポンス

`201 Created` とともに、エンドポイント、そのバージョンを示す `ETag`、およびシークレットが返されます。その他のフィールドについては [ウェブフックエンドポイントを取得する](get.md) を参照してください。

```json
{
  "id": "whe_01k8a3m5q7t9v1w3x5y7z9b2c4",
  "key": "crm-sync",
  "url": "https://hooks.example.com/keenauth",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"],
  "event_schema_versions": {},
  "payload_mode": "thin",
  "status": "enabled",
  "rate_limit_per_second": 50,
  "previous_secret_expires_at": null,
  "last_success_at": null,
  "failing_since": null,
  "version": 1,
  "created_at": "2026-10-26T09:00:00Z",
  "updated_at": "2026-10-26T09:00:00Z",
  "signing_secret": "idp_whsec_<secret>"
}
```

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 400 | `unknown_field` | 上記に記載のないフィールドがボディに含まれています。 |
| 403 | `quota_exceeded` | 環境で有効にできるエンドポイント数がプランの上限に達しているか、プランが不明です。 |
| 409 | `conflict` | 同じ環境内の別のエンドポイントがこの `key` を使用しています。 |
| 422 | `validation_failed` | `/url required`、`/url invalid_webhook_url`、`/key invalid`、`/description too_long`、`/event_types unknown_event_type`、`/event_types duplicate`、`/event_types too_many`、`/event_schema_versions unsupported_schema_version`、`/payload_mode invalid`、`/rate_limit_per_second out_of_range`、`/status invalid`。 |
| 422 | `idempotency_key_reuse` | `Idempotency-Key` が別のリクエストで使用されています。 |
| 401 | `unauthenticated` | 認証情報が欠落しているか、無効または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に `webhook-endpoints:write` 権限がありません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を待ってから再試行してください。 |
| 503 | `service_unavailable` | ウェブフックの管理機能は一時的に利用できません。`Retry-After` の期間を待ってから再試行してください。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f" \
  -d '{"url":"https://hooks.example.com/keenauth","key":"crm-sync","event_types":["user.created","user.updated"]}'
```

CLI: `keenauth webhook-endpoints create --url https://hooks.example.com/keenauth --key crm-sync --event-types user.created,user.updated`