API リファレンス

基本

URL

https://api.webhookadmin.com/v1

認証

Authorization: Bearer sk_live_… か sk_test_…。キーの環境の中だけを読み書きします

形式

JSON。時刻は Unix ミリ秒、ID は接頭辞付きの文字列

本文の上限

1.1MB（超えると 413 too_large）

一覧

?cursor=&limit=（limit は 1〜100、既定 50）。返りは { items, next_cursor }

一覧の cursor とメッセージ・送信の ID は、保存期間の最古の月から今月までのものだけ受け付けます（外れた cursor は 422、ID は 404）。

エラー

{ "error": "<code>", "message": "<説明>" }

回数制限

1 分あたりの回数を、環境ごとに全部のキーを合わせて数えます。

エンドポイント

メッセージの送信

POST /v1/messages

権限: messages:send

返り: 202 { id, deliveries }。deliveries は作った送信の数。

• 同じ Idempotency-Key は 24 時間のあいだ同じ id を返します（本文が違っても最初のもの）。
• consumer の顧客が無ければ、その場で作ります（送信先が無いので deliveries は 0）。
• 応答ヘッダー x-usage-month に、組織の今月（UTC）の本番の送信数が入ります。
• テスト環境の送信と試しの送信は料金の対象外で、1 つの環境で 1 日（UTC）1,000 通までです。超えると 402 plan_limit。

メッセージの一覧

GET /v1/messages

権限: logs:read

クエリ: status（pending / retrying / success / failed）・event_type・q・since（Unix ミリ秒。この時刻以降に作られたもの）・cursor・limit。

q はメッセージの ID・イベントの種類・顧客の external_id・Idempotency-Key の部分一致です。本文の中身は探しません。

q・status・event_type を付けて since を省くと、直近 7 日に作られたメッセージだけを返します。

返り: { items: MessageRow[], next_cursor }。

メッセージの詳細

GET /v1/messages/{id}

権限: logs:read

返り: MessageDetail（本文と、送信先ごとの送信・試行）。

送信のやり直し

POST /v1/deliveries/{id}/retry

権限: messages:retry

id は Delivery の ID。返り: 202。

顧客の一覧

GET /v1/consumers

権限: logs:read

クエリ: cursor・limit。返り: { items: Consumer[], next_cursor }。

顧客の作成

POST /v1/consumers

権限: consumers:write

返り: 201 Consumer。同じ external_id の顧客があるときは 409 conflict。

顧客向けの設定画面のリンクの作成

POST /v1/consumers/{id}/portal

権限: endpoints:write

返り: 201 { url, expires_at }。url は 15 分で切れ、期限までは何度でも開けます。Free のプランは 402 plan_limit、ほかの環境の顧客は 404。

自社の画面への埋め込み（src は返ってきた url）:

<iframe
  src="https://app.webhookadmin.com/portal/eyJlIjoi…?lang=ja"
  title="Webhook"
  allow="clipboard-write"
  style="display: block; width: 100%; height: 900px; border: 0"
></iframe>

• 埋め込めるのは frame_origin のオリジンだけです。frame_origin の無いリンクは iframe の中に表示されません（Content-Security-Policy: frame-ancestors）。
• 画面はクッキーを使わず、リンクのトークンで動きます。別のドメインの iframe（Safari を含む）の中でも使えます。
• 顧客ができること: 送信先の登録・編集・一時停止・削除、受け取るイベントの選択、署名の鍵の表示と切り替え、試しの送信、配信記録と再送。
• url にクエリ theme=dark を足すと暗い配色になります。

送信先の一覧

GET /v1/endpoints

権限: logs:read

クエリ: consumer_id（任意）。返り: { items: Endpoint[] }。

送信先の作成

POST /v1/endpoints

権限: endpoints:write

返り: 201 Endpoint と secret（署名の鍵。このときだけ）。

• URL は https（ポート 443 か 8443）。
• IP アドレスを直接書いた URL・社内向けの名前・社内アドレスを指す名前・名前が引けないものは 422。
• 1 つの顧客に登録できる送信先は 20 までです。超えると 422。

送信先の詳細

GET /v1/endpoints/{id}

権限: logs:read

返り: Endpoint と recent: AttemptRow[]・retrying_count・recovery（最後のまとめて再送。無ければ null）。

送信先の変更

PATCH /v1/endpoints/{id}

権限: endpoints:write

入力（すべて任意）: url・event_types・status（active / paused）・description・retry・compat_signature。返り: Endpoint。

• paused にした送信先あての送信は保留になり、active に戻すと今月と先月の保留分をまとめて送ります。
• 自動で止まった送信先（disabled）は、status を active にすると戻ります。
• retry は null で既定に戻り、compat_signature は null で外れます。

送信先の削除

DELETE /v1/endpoints/{id}

権限: endpoints:write

返り: 204。

署名の鍵の切り替え

POST /v1/endpoints/{id}/rotate-secret

権限: endpoints:write

返り: { secret }。古い鍵の署名も 24 時間は付けて送ります。

まとめて再送

POST /v1/endpoints/{id}/recover

権限: messages:retry

返り: 202 Recovery。進み具合は まとめて再送の状態 で確かめます。

• この送信先に届かずに失敗で終わった送信を、同じメッセージ（同じ webhook-id）のまま送り直します（まとめて再送）。
• 送信先が active でないときは 409 conflict。再開してから呼びます。
• 1 つの送信先で動けるのは 1 つだけです。動いているあいだは 409 conflict。

まとめて再送の状態

GET /v1/endpoints/{id}/recoveries/{recovery_id}

権限: logs:read

返り: Recovery。status は running（送っている途中）・done（終わった）・stopped（途中で送信先が止まった・削除された）。

イベントの種類の一覧

GET /v1/event-types

権限: 不要（環境のキーならどれでも）

返り: { items: EventType[] }（名前の順。ページ送りはありません）。

イベントの種類の登録

POST /v1/event-types

権限: endpoints:write

返り: 201 EventType。同じ name の種類があるときは 409 conflict。

登録した種類は、管理画面と顧客向けの設定画面で送信先の種類を選ぶときの候補になります。

再送の設定

再送の回数と間隔は送信先ごとに選べます。管理画面・API（retry）・MCP・顧客向けの設定画面で設定します。

{ "retry": { "count": 3, "interval": "5m" } }

• 既定は count: 7・interval: progressive です（最初の送信を含めて最大 8 回、約 28 時間）。retry: null で既定に戻ります。
• 最初の送信から最後の再送までが 3 日を超える組み合わせは選べません（422）。当たるのは progressive と 12 の組み合わせです。
• 失敗が 5 日続いた送信先の自動停止は、再送の設定とは別に数えます。

まとめて再送

送信先の障害が直ったあと、その送信先に届かずに失敗で終わった送信を、指定した時刻以降の分だけまとめて送り直します。同じメッセージ（同じ webhook-id）のまま送るので、受け側は処理済みの ID を捨てられます。

管理画面

送信先の詳細

API

POST /v1/endpoints/{id}/recover（入力と返り）

MCP

recover_endpoint・get_recovery

顧客向けの設定画面

顧客が自分の送信先について実行できます

• キューで少しずつ送ります（10 秒ごとに 50 通）。送信先の同時接続の枠が埋まっているあいだは待ちます。
• 対象は、始めた時点で失敗で終わっていた送信です。その後に失敗したものや、1 通ずつ送り直したものは含みません。
• 自動で止まっていた（disabled）あいだのメッセージは、送信先あての記録が無いため対象になりません。一時停止（paused）のあいだの送信は保留になっており、再開したときに送ります。
• 途中で送信先を止める・削除すると、そこで終わります（stopped）。
• 使用量には数えません。

失敗の通知の条件

失敗の通知（Slack・Teams・Chatwork・メール・Webhook）をいつ送るかを組織ごとに選べます。管理画面の「失敗の通知」の「知らせる条件」か、MCP の update_alert_conditions で設定します。条件はすべての通知先で共通です。

• 送信の失敗は、どの設定でも再送を使い切ったときに知らせます。同じ送信先の通知は 1 時間に 1 回までです。
• 同じ組織への送信の失敗の通知は、1 時間に 1 通まですぐ送ります。その 1 時間に失敗し始めたほかの送信先は、1 時間ごとに 1 通にまとめて送ります。
• 再送待ちの件数は送信先ごとではなく、環境の合計で数えます。
• 組織の owner には、この条件とは別に、使用量が上限の 80%・100% に届いたときにメールで知らせます。

型

MessageRow    = { id, event_type, consumer: { id, external_id, name }, created_at,
                  status: 'success' | 'retrying' | 'failed' | 'pending', attempts, endpoint_url }
MessageDetail = { id, event_type, consumer, created_at, idempotency_key, payload, deliveries: Delivery[] }
Delivery      = { id, endpoint_id, url, status: 'pending' | 'success' | 'retrying' | 'failed',
                  attempt_count, next_attempt_at, attempts: AttemptRow[] }
AttemptRow    = { id, at, response_status, response_head, duration_ms, error,
                  via: 'direct' | 'relay', source_ip }
Consumer      = { id, external_id, name, created_at, endpoint_count }
Endpoint      = { id, consumer_id, url, description, event_types: string[] | null, fixed_ip,
                  status: 'active' | 'paused' | 'disabled', disabled_reason, failing_since, created_at,
                  retry: RetryPolicy, compat_signature: CompatSignature | null }
RetryPolicy   = { count: 0 | 1 | 2 | 3 | 5 | 7 | 12,
                  interval: 'progressive' | '1m' | '5m' | '30m' | '1h' | '6h' }
CompatSignature = { header, content: 'body' | 'timestamp_body', encoding: 'hex' | 'base64', prefix }
Recovery      = { id, endpoint_id, since, status: 'running' | 'done' | 'stopped',
                  total, queued, created_at, finished_at }
EventType     = { name, description, archived_at }