API リファレンス

Webhook エンドポイント

Webhook エンドポイント一覧

現在の Workspace の Webhook エンドポイントを一覧表示します。購読イベント、署名状態、ステータス、リトライポリシーを含みます。

GEThttps://api.unifyport.ai/v1/webhook-endpoints

対応チャネル

all

呼び出す前に

対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。

パラメーターの取得元
account_id
アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。 アカウント取得

リクエストパラメータ

ヘッダー

X-Api-Key
string必須

ワークスペース API キー。このヘッダーからワークスペースを特定します。

クエリパラメータ

account_id
string

任意の公開アカウント 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
      }
    }
  ]
}

レスポンスボディ

id
string

Webhook エンドポイント識別子（we_...）。

account_id
string

アカウント独自のエンドポイントの公開アカウント ID。ワークスペースのエンドポイントでは省略され、null は返しません。

minLength: 1

url
string

Webhook 配信を受け取る絶対 HTTP(S) URL。production では HTTPS を推奨します。

format: uri

status
string

エンドポイントのステータス: active または inactive。

enum: active, inactive

subscribed_events[]
string[]

エンドポイントに配信される公開標準イベント種別。["*"] は公開イベントをすべて意味し、provider.raw_event は含みません。

signing_enabled
boolean

署名シークレットが設定され配信が署名される場合は true。

retry_policy
object

max_attempts は初回配信後のリトライ回数で、既定 3、範囲 0〜5。

max_attempts
integer

設定済みの初回配信後リトライ回数（0〜5）。

レスポンス

200

200 OK

リクエスト成功。レスポンスボディの例を参照してください。

400

Bad Request

リクエストボディ、パス、またはパラメータが不正です。

401

Unauthorized

X-Api-Key ヘッダが欠落しているか無効です。

404

Not Found

要求されたリソースが見つかりません。error.code と現在の操作を合わせて確認してください。

500

Internal Server Error

サービスで予期しないエラーが発生しました。

失敗時の対応

HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。 エラーリファレンス

invalid_request · 10000 · 400
必須項目、形式、チャネルの条件を確認して修正します。
missing_api_key · 11000 · 401
X-Api-Key とワークスペースの有効性を確認します。
invalid_api_key · 11001 · 401
X-Api-Key とワークスペースの有効性を確認します。