Skip to content

Webhook

タスク・コメント・レビューのイベントを、登録した外部の URL へ署名付きで送る

概要

プロジェクトで起きたイベントを、登録した外部の 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 は認証情報を含みうる

Type to search…

↑↓ navigate↵ selectEsc close