API リファレンス

Webhook エンドポイント

Webhook エンドポイント更新

Webhook を更新します。url は絶対 HTTP(S) で production では HTTPS を推奨、status は active / inactive です。空の signing_secret で署名を無効化し、max_attempts は 0..5 です。

PATCHhttps://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}

呼び出す前に

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

PATCH は Webhook 設定を置き換えます。保持する設定をすべて送信してください。signing_secret を省略すると署名が無効になり、subscribed_events を省略すると全公開イベントが対象となります。retry_policy/max_attempts を省略すると再試行は既定の 3 回に戻ります。既存設定を読み取り、保存済みの署名シークレットを指定してください。

リクエストパラメータ

ヘッダー

X-Api-Key
string必須

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

Content-Type
string必須

JSON のリクエストボディを送る場合は application/json を使用します。

パスパラメータ

endpoint_id
string必須

webhook endpoints ルートで使用される識別子。

リクエストボディ

url
string必須

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

format: uri

status
string必須

エンドポイントの状態: active または inactive。

enum: active, inactive

subscribed_events[]
string[]

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

signing_secret
string

任意の Webhook 署名シークレット。サンプルではプレースホルダを使用してください。

retry_policy
object

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

max_attempts
integer

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

結果の確認

設定の成功は配信成功ではありません。関連イベントを発生させ、受信側で到着・署名・応答を確認します。

レスポンス 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
    }
  }
}

レスポンスボディ

id
string

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

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 ヘッダが欠落しているか無効です。

失敗時の対応

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

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