概要
プロジェクトで起きたイベントを、登録した外部の URL へ送る機能である。プロジェクトの管理者が URL・購読するイベント・本文の形を登録し、配信は再試行付きの掃き出しループが行う。本文の形は署名付きの JSON と Discord の Incoming Webhook の 2 つである。外部から受け取る GitHub の Webhook は範囲外で、GitHub App 基盤に書く。
振る舞い
イベント
購読できるイベントは次のとおりである。
| イベント | トリガー |
|---|---|
task.created |
タスク作成 API |
comment.created |
コメント投稿 API |
review.round_created |
レビューラウンドの起票 |
review.finding_changed |
指摘の状態遷移 |
- 4 つのイベントは、利用者の操作を受ける API ハンドラーだけが発火する。GitHub Issue の取り込みや webhook の同期で作られたタスクでは
task.createdを送らない - 一括作成(
POST /tasks/bulk-create)では、作成した件数分のtask.createdが届く(まとめて 1 回にはならない) - 配信はイベントを起こした操作と同じトランザクションで
webhook_deliveriesに積む(service::webhooks::emit)。操作が巻き戻れば配信も残らない - 止まっている Webhook(
is_active = false)には積まない
リクエストヘッダー
送信するヘッダーは次のとおりである。
Content-Type: application/json
X-Task-Event: task.created
X-Task-Delivery: <webhook_deliveries.id>
X-Task-Signature: sha256=<HMAC-SHA256-hex> ← format=json のときだけ受信側は次の式で署名を検証する。
"sha256=" + hex(HMAC-SHA256(secret, raw_request_body)) == X-Task-Signature の値同じ配信の再試行は X-Task-Delivery が同じである。手動再送は新しい配信なので別の値になる。User-Agent は koyori-webhook である。
共通フィールド
すべてのイベントが次を持つ。review.finding_changed の actor だけはイベント固有のフィールドの小節に書く例外がある。
{
"event": "task.created",
"timestamp": "2026-05-27T10:00:00Z",
"project_id": "uuid",
"project": { "id": "uuid", "key": "ENG", "name": "Engineering" },
"actor": { "id": "uuid", "username": "alice" }
}イベント固有のフィールド
task.created の固有のフィールドは次のとおりである。
{
"task": {
"id": "uuid", "seq_id": 42,
"title": "OAuth 対応を実装する",
"priority": "high",
"status": "Backlog",
"assignees": [{ "user_id": "uuid", "role": "primary" }],
"hard_deadline": "2026-06-10T00:00:00Z",
"created_by": "uuid"
}
}comment.created の固有のフィールドは次のとおりである。
{
"task": { "id": "uuid", "seq_id": 42, "title": "OAuth 対応を実装する" },
"comment": { "id": "uuid", "author": "alice", "body": "本文" }
}コメント本文のメンションのマーカー(<@利用者ID>)は @今の名前 に戻して送る。マーカーは利用者 ID を含むので、そのまま外へ出さない。
review.round_created / review.finding_changed は in-app 通知(review_round_created / review_finding_changed)の payload と同じ中身である。service::notifications::review_round_payload / review_finding_payload を共有する。
emit はイベント固有のフィールドで共通フィールドを上書きする。review.finding_changed の payload は actor を名前の文字列で持つので、このイベントの actor は共通フィールドの object ではなく文字列("alice")になる。review.round_created の payload は actor を持たないので、共通フィールドの object のまま届く。
review.round_created の固有のフィールドは次のとおりである。
{
"review_id": "uuid", "repo": "owner/name", "pr_number": 618, "round": 2,
"head_sha": "60cdd77…", "reviewer": "alice",
"counts": { "high": 1, "medium": 2, "low": 0, "nit": 0 },
"summary_excerpt": "総評の先頭 200 文字"
}指摘の引き継ぎで作った写しのラウンドのときだけ、carried_by(引き継いだ人の名前)と carried_from({ "review_id", "pr_number", "round" }。元のラウンドが無くなっていれば null)も入る。reviewer は元のラウンドの作成者のままである。
review.finding_changed の固有のフィールドは次のとおりである。to = deferred のときは繰り延べ先タスクの deferred_task_id も入る。
{
"review_id": "uuid", "finding_id": "uuid", "repo": "owner/name", "pr_number": 618, "round": 2,
"title": "指摘のタイトル", "severity": "high", "from": "open", "to": "fixed",
"actor": "alice", "note": null
}Discord の形
format=discord では、Discord の Incoming Webhook URL をそのまま登録でき、本文を Discord の形に変える。本文の例は次のとおりである。
{
"content": "[Koyori] PR #618 のレビュー R2(high 1 / medium 2 / low 0 / nit 0)",
"embeds": [{
"title": "レビューの投稿",
"color": 10181046,
"description": "alice が PR #618 のレビュー R2 を起票しました。…",
"fields": [
{ "name": "プロジェクト", "value": "Engineering", "inline": true },
{ "name": "実行者", "value": "alice", "inline": true }
],
"timestamp": "2026-10-20T01:23:45Z"
}]
}embed の見出しと色はイベントごとに次のとおりに決める。イベント名(review.round_created など)は見出しに出さない。
| イベント | 見出し | 色 |
|---|---|---|
task.created |
タスクの作成 | 緑 #2ecc71 |
comment.created |
コメントの追加 | 青 #3498db |
review.round_created |
レビューの投稿 | 紫 #9b59b6 |
review.finding_changed |
レビュー指摘の更新 | 橙 #e67e22 |
ほかの項目は次のとおりである。
timestampは payload のtimestamp(イベントの発生時刻)である。Discord はこれを投稿時刻として表示する- レビュー系の要約は通知メールの件名・本文 1 行目と同じ文言である(
service::notification_email::subject_and_line) task.createdのdescriptionはステータスと優先度、comment.createdのdescriptionはコメント本文であるfieldsの「実行者」はactor.usernameから作る。actorが文字列になるreview.finding_changedではこの field が付かない- 値が空の field は Discord が受け付けないので落とす
contentは 2000 文字、descriptionは 4096 文字で切る。Discord の上限である- 署名ヘッダは付けない。Discord は検証せず、URL 自体が秘密である
配信と再試行
job::webhook_delivery の掃き出しループが 10 秒ごとに、next_attempt_at <= now() の配信を next_attempt_at の古い順に最大 50 件拾って送る。1 件ごとに短いトランザクションで FOR UPDATE SKIP LOCKED を取り直し、同じ Webhook の行もロックして送信結果を確定する。複数インスタンスでも同じ配信を二重に送らず、連続失敗数を送信順に更新する。
送信の結果は次のとおりに扱う。
- 1 回の送信の timeout は 10 秒である。リダイレクトは追わず、3xx は失敗とする
2xxならdelivered_atを立てて完了し、Webhook のfailure_streakを 0 に戻す- それ以外と接続失敗は
attemptを進め、次の試行を予約する - 5 回失敗したら打ち止め(
next_attempt_at = NULL)にし、Webhook のfailure_streakを 1 増やす failure_streakが 5(打ち止めが 5 本連続)になったらwebhooks.is_active = falseにする- 止まった Webhook の送信待ちは送らずに完了にする(
last_error = "webhook is inactive") - 完了した配信履歴は 90 日で消す。同じループが 1 時間に 1 回
created_atで掃除する。送信待ちは残す
各回の試行の時機は次のとおりである。
| 試行 | 時機 |
|---|---|
| 1 回目 | 即時。次の掃き出しで送るので最大 10 秒遅れる |
| 2 回目 | 30s |
| 3 回目 | 5m |
| 4 回目 | 30m |
| 5 回目 | 2h |
送信先の検証
SSRF を防ぐため、service::webhooks::resolve_url で作成・更新時と送信の直前に名前解決し、全アドレスを検証する。送信時はその検証済み IP に接続を固定し、接続時の再解決を防ぐ。元のホスト名は Host ヘッダと TLS の検証に使う。
https必須である。httpは localhost のみ許す- private / link-local / CGNAT / NAT64 / 予約済み IP / メタデータ(
169.254.169.254)宛てと、それらへ解決される名前は拒否する - loopback(
localhost/127.0.0.0/8/::1。IPv4-mapped IPv6 と DNS の解決先も含む)は既定では拒否する。開発・テストでのみWEBHOOK_ALLOW_LOOPBACK=trueを明示して許可する - 名前解決の上限は 10 秒で、解決できないときも拒否する
- 作成・更新時の拒否は 400 である。送信時の拒否は配信の失敗として数える
- リダイレクトは追わず、環境変数の HTTP プロキシも使用しない
データ
webhooks の列は次のとおりである。
| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
id |
UUID | PK | |
project_id |
UUID | NOT NULL, FK→projects CASCADE | |
url |
VARCHAR(2048) | NOT NULL | 送信先 URL。送信先の検証を通ったもの |
secret_enc |
VARCHAR | NOT NULL | HMAC-SHA256 署名用シークレットを暗号化した値(auth_core::crypto::encrypt_token、鍵は TOTP_ENCRYPTION_KEY)。平文は作成時の応答でだけ返す |
events |
VARCHAR[] | NOT NULL | 購読するイベント名。1 つ以上 |
format |
VARCHAR | NOT NULL DEFAULT 'json', CHECK json / discord(chk_webhooks_format) |
本文の形 |
is_active |
BOOLEAN | NOT NULL DEFAULT true | 連続失敗で自動的に false になる |
failure_streak |
SMALLINT | NOT NULL DEFAULT 0 | 打ち止めになった配信の連続数。成功で 0、is_active を true に戻すと 0 |
created_by |
UUID | NOT NULL, FK→users | |
created_at |
TIMESTAMPTZ | NOT NULL DEFAULT now() |
webhook_deliveries の列は次のとおりである。配信の行そのものが送信待ちの行列(outbox)を兼ねる。
| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
id |
UUID | PK | X-Task-Delivery ヘッダの値 |
webhook_id |
UUID | NOT NULL, FK→webhooks CASCADE | |
event |
VARCHAR | NOT NULL | |
payload |
JSONB | NOT NULL | 送信ペイロード。format=json の本文そのもの |
status_code |
INT | NULLABLE | 最後の試行の HTTP レスポンスコード。接続失敗なら NULL |
attempt |
SMALLINT | NOT NULL DEFAULT 0 | 試行した回数。最大 5 |
next_attempt_at |
TIMESTAMPTZ | NULLABLE | 次に試す時刻。NULL は完了(成功・打ち止め・Webhook 停止)である |
last_error |
TEXT | NULLABLE | 最後の失敗の理由 |
delivered_at |
TIMESTAMPTZ | NULLABLE | 成功時のみ |
created_at |
TIMESTAMPTZ | NOT NULL DEFAULT now() |
列とインデックスの定義は m20260922020000_webhooks.rs にある。
API
パスは /v1/tenants/{tenant_id}/projects/{project_id}/webhooks 配下である。
| メソッド | パス | 説明 |
|---|---|---|
| GET | / |
一覧。secret は返さない。完全な URL は管理者にのみ返す |
| POST | / |
作成(201)。secret は作成時のみ平文で返す |
| PUT | /{id} |
更新。有効 / 無効の切り替えもこれで行う |
| DELETE | /{id} |
削除(204)。配信履歴も消える |
| GET | /{id}/deliveries?limit= |
配信履歴。新しい順で、limit は既定 50・1〜100 |
| POST | /{id}/deliveries/{did}/redeliver |
手動再送(201)。同じ payload で新しい配信を積み、元の行は変えない |
作成と更新の検証は次のとおりである。
| フィールド | 検証 |
|---|---|
url |
2048 文字以内。送信先の検証を通ること |
secret |
16 文字以上 |
events |
イベントの小節の 4 つの部分集合。空は不可 |
format |
json(既定)/ discord |
PUT /{id}はurl/secret/events/format/is_activeのうち指定したものだけ変える- 有効 / 無効の切り替え専用のエンドポイント(
POST /{id}/toggle)は無く、PUTのis_activeで行う。is_activeに true を送るとfailure_streakも 0 に戻る - 他プロジェクトの Webhook / 配信の ID は 404 を返す
- イベントの小節に無いイベントは購読できず、作成・更新で 400 を返す
- 一覧は、管理権限のない利用者には送信先 URL を形式を問わず
[redacted]で返す。write:projectを持たない PAT も、ロールによらず同じ扱いである - 管理者の一覧・作成・更新の応答では完全な URL を返す。配信エラーには URL を残さない
認可
| 操作 | 誰が | スコープ |
|---|---|---|
| 一覧 | プロジェクトを読める利用者 | read:project |
| 作成・更新・削除 | プロジェクト Admin | write:project |
| 配信履歴の取得・手動再送 | プロジェクト Admin | write:project |
プロジェクト Admin は、プロジェクトの Admin ロール、テナントオーナー、またはそのプロジェクトに入れるテナント Admin である(require_project_admin)。
画面
| 項目 | 値 |
|---|---|
| 入口 | プロジェクト設定 > Webhook(?section=webhooks) |
| コンポーネント | WebhooksSection.vue / WebhookFormDialog.vue |
一覧
- 送信先(管理者には完全な URL、それ以外には
[redacted])・形式(JSON / Discord)・購読イベント・状態(有効 / 無効)を出す failure_streak > 0なら「連続失敗 N 回」と出す- 連続失敗で止まったもの(
is_active = falseかつfailure_streak >= 5)は「連続失敗で停止」と出す - 行の操作は、編集、無効にする・有効にする(
PUT { is_active }。有効に戻すと連続失敗も 0 に戻る)、削除(確認ダイアログ)、配信履歴である
作成と編集
- 作成・編集はダイアログで行う
- secret は作成時は必須(16 文字以上)、編集時は空欄なら変更しない
- 編集は変えたフィールドだけ
PUTする - 一覧が
[redacted]を返した送信先 URL は欄に出さず、secret と同じく空欄なら変更しない - secret は作成直後に同じダイアログで一度だけ表示し、コピーできる。閉じたら再表示できず、API も返さない。失くしたら編集で新しい値に差し替える
配信履歴
- 行の下に展開し、新しい順に 20 件を出す
- 結果は「成功 (HTTP N)」「送信待ち」「再試行待ち (n 回目、次回 時刻)」「失敗 (n 回)」と最後のエラーである
- payload は折りたたみで見られる
- 「再送」は redeliver を呼び、新しい配信が履歴の先頭に増える
変更系の 403 は「この操作にはプロジェクトの管理者権限が必要です」と出す。ボタンは権限に関わらず表示する。
未実装と既知の制限
未実装のイベントは次のとおりである。購読できない。
| イベント | トリガー |
|---|---|
task.updated |
タスクのフィールド変更(差分のみ) |
task.deleted |
タスク削除 |
task.archived / task.unarchived |
アーカイブ操作 |
github.pr_linked |
PR リンク追加 |
github.pr_merged |
PR マージ |
sprint.started / sprint.completed |
スプリント状態変化 |
連続失敗で止まったときのテナントオーナーへのメール通知は未実装である。通知メール(通知・ウォッチャー)は利用者ごとの購読で、運用者宛ての連絡とは別物である。
決定の記録
| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-09-23 | 配信はジョブキュー(apalis)ではなく、配信の行を outbox にした掃き出しループで行う | イベントを起こす service からは apalis へ積めない(依存の向きが service → job)ので、通知メールと同じ形にした |
| 2026-09-23 | secret の暗号化鍵は TOTP_ENCRYPTION_KEY にする |
起動に必須の鍵なので、GitHub App を設定していない環境でも Webhook を使える。GITHUB_TOKEN_ENCRYPTION_KEY は GitHub App 設定時にしか無い |
| 2026-09-23 | 送信は共有の HTTP クライアントではなく、リダイレクトを追わない専用のクライアントで行う | 検証済みの URL から private な宛先へ 302 で飛ばされるのを防ぐ |
| 2026-09-23 | 送信の直前にも名前解決して検証する | DNS の向き先は登録後に変えられる |
| 2026-09-27 | 送信先 URL を管理権限のない利用者に返さない | 送信先 URL は認証情報を含みうる |
