Webhook エンドポイント
Webhook エンドポイント一覧
現在の Workspace の Webhook エンドポイントを一覧表示します。購読イベント、署名状態、ステータス、リトライポリシーを含みます。
https://api.unifyport.ai/v1/webhook-endpoints対応チャネル
呼び出す前に
対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。
パラメーターの取得元
- account_id
- アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。 アカウント取得
リクエストパラメータ
ヘッダー
X-Api-Keyワークスペース API キー。このヘッダーからワークスペースを特定します。
クエリパラメータ
account_id任意の公開アカウント ID(例: acc_example)。空文字列、空白のみ、重複指定は不可。パラメータ名は正確に account_id とし、大文字・小文字の異なる表記は省略扱いではなく 400 invalid_request になります。一覧で省略するとワークスペースのエンドポイントのみ、指定するとアカウント独自の設定のみを返します(独自設定がなければ data=[]、継承したワークスペース設定は含みません)。取得・無効化・削除では既存のアカウント帰属のみを検証し、不一致は 400 invalid_request になります。指定したアカウントが存在しないか現在のワークスペースに属さない場合は 404 account_not_found (20020) になります。
minLength: 1 · pattern: \S
リクエストボディ
このエンドポイントは JSON ボディを必要としません。
結果の確認
エンドポイントの所属、status、購読イベント、signing_enabled、再試行設定を確認します。取得成功で確認できるのは設定であり、イベント配信の成功ではありません。
レスポンス 200 OK
{
"request_id": "<REQUEST_ID>",
"data": [
{
"id": "we_example",
"url": "https://example.com/webhook",
"status": "active",
"subscribed_events": [
"message.received"
],
"signing_enabled": true,
"retry_policy": {
"max_attempts": 3
}
}
]
}
レスポンスボディ
idWebhook エンドポイント識別子(we_...)。
account_idアカウント独自のエンドポイントの公開アカウント ID。ワークスペースのエンドポイントでは省略され、null は返しません。
minLength: 1
urlWebhook 配信を受け取る絶対 HTTP(S) URL。production では HTTPS を推奨します。
format: uri
statusエンドポイントのステータス: active または inactive。
enum: active, inactive
subscribed_events[]エンドポイントに配信される公開標準イベント種別。["*"] は受信資格のある公開イベントを意味し、provider.raw_event は含みません。
signing_enabled署名シークレットが設定され配信が署名される場合は true。
retry_policyobjectmax_attempts は初回配信後のリトライ回数で、既定 3、範囲 0〜5。
retry_policymax_attempts は初回配信後のリトライ回数で、既定 3、範囲 0〜5。
max_attempts設定済みの初回配信後リトライ回数(0〜5)。
レスポンス
200200 OK
リクエスト成功。レスポンスボディの例を参照してください。
400Bad Request
リクエストボディ、パス、またはパラメータが不正です。
401Unauthorized
X-Api-Key ヘッダが欠落しているか無効です。
403Forbidden
リクエストは識別されましたが、この操作は許可されていません。
404Not Found
要求されたリソースが見つかりません。error.code と現在の操作を合わせて確認してください。
500Internal Server Error
サービスで予期しないエラーが発生しました。
失敗時の対応
HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。 エラーリファレンス
HTTP ステータス、error.code、error.numeric_code を現在の操作と合わせて確認します。数値コードは文字列です。request_id は調査用で、冪等性キーやタスク ID ではありません。
- invalid_request · 10000 · 400
JSON 本文と必須項目を確認してください。
対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。
JSON の例です。message は実際の原因によって変わります · 400 · 10000
{ "request_id": "req_example", "error": { "code": "invalid_request", "numeric_code": "10000", "message": "Invalid request parameters" } }- invalid_target_workspace · 11003 · 400
上書き対象のワークスペースが空、または形式が無効です。上書き用ヘッダーを削除し、対象ワークスペースの API Key を使用してください。
発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。
対処と再試行: 操作とチャネルの条件に従ってパラメーターを修正してから再実行します。同じ無効なリクエストを繰り返しても解決しません。
JSON の例です。message は実際の原因によって変わります · 400 · 11003
{ "request_id": "req_example", "error": { "code": "invalid_target_workspace", "numeric_code": "11003", "message": "Invalid target workspace" } }- invalid_api_key · 11001 · 401
API Key が正しく有効か確認してください。
対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。
JSON の例です。message は実際の原因によって変わります · 401 · 11001
{ "request_id": "req_example", "error": { "code": "invalid_api_key", "numeric_code": "11001", "message": "Invalid API key" } }- missing_api_key · 11000 · 401
X-Api-Key ヘッダーを追加してください。
対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。
例 · 401 · 11000
{ "request_id": "req_xxx", "error": { "code": "missing_api_key", "numeric_code": "11000", "message": "Missing X-Api-Key header" } }- workspace_override_forbidden · 11002 · 403
この API Key に許可されていないワークスペースの上書きを要求しています。上書き用ヘッダーを削除し、対象ワークスペースの API Key を使用してください。
発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。
対処と再試行: request_id と構造化されたコードを保存し、現在の操作を調査してから次の対応を決めます。
JSON の例です。message は実際の原因によって変わります · 403 · 11002
{ "request_id": "req_example", "error": { "code": "workspace_override_forbidden", "numeric_code": "11002", "message": "Workspace override is not allowed" } }- account_not_found · 20020 · 404
account_id を確認し、アカウントが属するワークスペースの X-Api-Key を使います。このワークスペースにないアカウントには現在のキーでアクセスできません。
対処と再試行: 対象の識別子、所有範囲、現在のワークスペースを確認します。不存在やアクセス不可が確認された対象を、一時的なサービス障害として自動再試行しないでください。
JSON の例です。message は実際の原因によって変わります · 404 · 20020
{ "request_id": "req_example", "error": { "code": "account_not_found", "numeric_code": "20020", "message": "Account not found" } }- target_workspace_not_found · 11004 · 404
上書きで指定したワークスペースが存在しないか利用できません。所有範囲を確認し、上書き用ヘッダーを削除して対象ワークスペースの API Key を使用します。再試行で権限は増えません。
発生条件: ワークスペースを上書きする X-Workspace-Id リクエストヘッダーを送った場合に適用されます。
対処と再試行: 対象の識別子、所有範囲、現在のワークスペースを確認します。不存在やアクセス不可が確認された対象を、一時的なサービス障害として自動再試行しないでください。
JSON の例です。message は実際の原因によって変わります · 404 · 11004
{ "request_id": "req_example", "error": { "code": "target_workspace_not_found", "numeric_code": "11004", "message": "Target workspace not found" } }- list_webhook_endpoints_failed · 40000 · 500
Webhook エンドポイント一覧:サービスが有効な照会結果を返せませんでした。
対処と再試行: request_id を保存し、識別子とアカウントのアクセス範囲を確認します。原因を確認してから照会を再試行してください。照会失敗は空の結果やリソースの不存在を意味しません。
JSON の例です。message は実際の原因によって変わります · 500 · 40000
{ "request_id": "req_example", "error": { "code": "list_webhook_endpoints_failed", "numeric_code": "40000", "message": "Failed to list webhook endpoints" } }