Webhook の受信 URL と購読するイベントを登録します。
Webhook は現在 Beta 機能です。API、フィールド、および動作は今後のバージョンで変更される可能性があります。
POST /api/v1/forward/webhook/endpoints
リクエストヘッダー
| Header | 必須 | 説明 |
|---|---|---|
Authorization | はい | Bearer <PAT または管理者 SAT> |
Content-Type | はい | application/json |
Idempotency-Key | いいえ | 任意の冪等性キー。同じキーは同一リクエストにのみ再利用してください。 |
リクエストボディのパラメーター
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
url | string | はい | イベントを受信する HTTP または HTTPS URL。本番環境では HTTPS を推奨します。 |
description | string | いいえ | Endpoint の用途。 |
events | string[] | はい | 購読イベント。1 件以上必要です。* または namespace.name 形式の具体的なイベント名を指定できます。forward.* などの前方一致ワイルドカードはサポートされません。完全なイベント名とトリガーはサポート対象の公開イベントを参照してください。このカタログにあるイベントのみ Forward の配信契約の対象です。 |
metadata | object | いいえ | カスタム文字列のキーと値。 |
リクエスト例
レスポンス例
HTTP 201 Created
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|---|---|
id | string | Endpoint ID。不透明な文字列として保存してください。 |
url | string | イベント受信 URL。 |
description | string | Endpoint の説明。 |
events | string[] | 現在の購読イベント。 |
metadata | object | カスタムメタデータ。レスポンスにはプラットフォームが管理するフィールドが含まれる場合があります。 |
active | boolean | Endpoint が有効かどうか。新規作成時は true です。 |
signing_secret | string | Webhook 署名を検証するためのシークレット。このレスポンスでのみ返されます。 |
created_at | string | 作成日時。RFC 3339 形式。 |
signing_secret はレスポンス受信後すぐに安全に保存してください。一覧、取得、更新 API では再表示されません。
エラー
| HTTP | Type | 発生条件 |
|---|---|---|
400 | invalid_request_error | URL、イベント一覧、メタデータ、またはリクエストボディが不正です。 |
401 | authentication_error | 認証情報がない、無効、または期限切れです。 |
403 | permission_error | 現在のトークンでは Webhook を管理できません。 |
409 | conflict_error | 冪等性キーが既存リクエストと競合しているか、Endpoint 数が上限に達しています。 |
413 | invalid_request_error | リクエストボディが大きすぎます。 |
429 | rate_limit_error | リクエスト頻度が制限に達しています。 |

