Webhook エンドポイント
Webhook エンドポイントを停止
エンドポイントを削除せずに、Webhook エンドポイントの状態を inactive に設定します。
https://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}/deactivate対応チャネル
呼び出す前に
対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。
パラメーターの取得元
- account_id
- アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。 アカウント取得
リクエストパラメータ
ヘッダー
X-Api-Keyワークスペース API キー。このヘッダーからワークスペースを特定します。
パスパラメータ
endpoint_idwebhook endpoints ルートで使用される識別子。
クエリパラメータ
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=inactive を確認します。このエンドポイントへの新規配信は期待しないでください。無効化しても、すでに送信中のリクエストの取り消しは保証されません。
レスポンス 200 OK
{
"request_id": "<REQUEST_ID>",
"data": {
"id": "we_example",
"url": "https://example.com/webhook-updated",
"status": "inactive",
"subscribed_events": [
"message.delivered",
"message.read"
],
"signing_enabled": false,
"retry_policy": {
"max_attempts": 1
}
}
}
レスポンスボディ
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" } }- deactivate_webhook_endpoint_failed · 40004 · 500
Webhook エンドポイントを停止:停止・無効化の結果を確認できません。対処時にも停止するという元の目的を維持します。
対処と再試行: 停止・無効化が反映されたかを現在の状態で確認します。停止したいリソースを復旧のために起動・再接続しないでください。
JSON の例です。message は実際の原因によって変わります · 500 · 40004
{ "request_id": "req_example", "error": { "code": "deactivate_webhook_endpoint_failed", "numeric_code": "40004", "message": "Failed to deactivate webhook endpoint" } }- deactivate_webhook_endpoint_failed · 40006 · 500
この範囲に対象 Webhook エンドポイントが見つかりません。GET、PATCH、無効化は各操作の code と HTTP 500 を維持し、numeric_code=40006 で区別します。冪等な DELETE には適用されず、対象がない場合は 204 を返します。
対処と再試行: 対象の識別子、所有範囲、現在のワークスペースを確認します。不存在やアクセス不可が確認された対象を、一時的なサービス障害として自動再試行しないでください。
JSON の例です。message は実際の原因によって変わります · 500 · 40006
{ "request_id": "req_example", "error": { "code": "deactivate_webhook_endpoint_failed", "numeric_code": "40006", "message": "Webhook endpoint not found" } }