API リファレンス：Webhook

Webhook（webhooks）の操作です。共通の決まり（認証・レート制限・エラーの形）は概要を、型の詳細はスキーマを参照してください。

AI・コーディングエージェント向けにこのページの Markdown 版とllms.txtがあります。

GET /api/v1/webhook_endpoints

Webhook 送信先の一覧

operationId：listWebhookEndpoints　必要なスコープ：webhooks:write

応答

ステータス説明型
200成功WebhookEndpointListOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

POST /api/v1/webhook_endpoints

Webhook 送信先の作成

operationId：createWebhookEndpoint　必要なスコープ：webhooks:write

リクエストの本文（JSON）

型：WebhookEndpointIn（必須）

項目型必須説明
urlstring（null 可）——
eventsstring の配列—値：lead.captured・lead.abandoned・delivery.sent・delivery.failed・conversion.detected・usage.threshold_reached（今後増えることがある） 既定値 []

応答

ステータス説明型
201成功WebhookEndpointCreatedOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
409状態の衝突（invalid_request）。idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中）Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

GET /api/v1/webhook_endpoints/{endpoint_id}

Webhook 送信先の取得

operationId：getWebhookEndpoint　必要なスコープ：webhooks:write

パラメータ

名前場所型必須説明
endpoint_idパスstring（uuid）必須—

応答

ステータス説明型
200成功WebhookEndpointOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

DELETE /api/v1/webhook_endpoints/{endpoint_id}

Webhook 送信先の削除

operationId：deleteWebhookEndpoint　必要なスコープ：webhooks:write

パラメータ

名前場所型必須説明
endpoint_idパスstring（uuid）必須—

応答

ステータス説明型
204成功（本文なし）—
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

GET /api/v1/webhook_endpoints/{endpoint_id}/deliveries

Webhook の送信ログの一覧

operationId：listWebhookEndpointDeliveries　必要なスコープ：webhooks:write

パラメータ

名前場所型必須説明
endpoint_idパスstring（uuid）必須—
limitクエリinteger—1〜200・既定値 50
cursorクエリstring（null 可）——

応答

ステータス説明型
200成功WebhookDeliveryListOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error

POST /api/v1/webhook_deliveries/{delivery_id}/redeliver

Webhook の再送

operationId：redeliverWebhookDelivery　必要なスコープ：webhooks:write

同じ payload の送信を新しく積み直す（受け付けただけで送信は後から行うので 202）。

応答は新しく積んだ送信記録（status: pending）。

パラメータ

名前場所型必須説明
delivery_idパスstring（uuid）必須—

応答

ステータス説明型
202成功WebhookDeliveryOut
401APIキーが無効・失効（authentication_error）Error
403スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）Error
404対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404Error
409状態の衝突（invalid_request）。webhook_endpoint_disabled（停止中の送信先）／idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中）Error
422パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）Error
429レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行するError
5XXサーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）Error