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

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

## 概要

プロジェクトで起きたイベントを、登録した外部の URL へ送る機能である。プロジェクトの管理者が URL・購読するイベント・本文の形を登録し、配信は再試行付きの掃き出しループが行う。本文の形は署名付きの JSON と Discord の Incoming Webhook の 2 つである。外部から受け取る GitHub の Webhook は範囲外で、[GitHub App 基盤](https://docs.koyori.app/dev/features/tasks/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`）には積まない

### リクエストヘッダー

送信するヘッダーは次のとおりである。

```text
Content-Type: application/json
X-Task-Event: task.created
X-Task-Delivery: <webhook_deliveries.id>
X-Task-Signature: sha256=<HMAC-SHA256-hex>   ← format=json のときだけ
```

受信側は次の式で署名を検証する。

```text
"sha256=" + hex(HMAC-SHA256(secret, raw_request_body)) == X-Task-Signature の値
```

同じ配信の再試行は `X-Task-Delivery` が同じである。手動再送は新しい配信なので別の値になる。`User-Agent` は `koyori-webhook` である。

### 共通フィールド

すべてのイベントが次を持つ。`review.finding_changed` の `actor` だけは[イベント固有のフィールド](#イベント固有のフィールド)の小節に書く例外がある。

```json
{
  "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` の固有のフィールドは次のとおりである。

```json
{
  "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` の固有のフィールドは次のとおりである。

```json
{
  "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` の固有のフィールドは次のとおりである。

```json
{
  "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` も入る。

```json
{
  "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 の形に変える。本文の例は次のとおりである。

```json
{
  "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](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/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` | スプリント状態変化 |

連続失敗で止まったときのテナントオーナーへのメール通知は未実装である。通知メール（[通知・ウォッチャー](https://docs.koyori.app/dev/features/tasks/notifications)）は利用者ごとの購読で、運用者宛ての連絡とは別物である。

## 決定の記録

| 日付 | 決定 | 理由 |
|---|---|---|
| 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 は認証情報を含みうる |

Source: https://docs.koyori.app/dev/features/tasks/webhooks/index.mdx
