Backlogの通知・Webhook・API実務ガイド：外部ツール連携と督促を設計する

課題管理とバーンダウンチャートの先にある、外部への接続という設計

「Backlogの課題管理実務ガイド」で課題・ドキュメント・ガントチャートをつなぐ設計を、「Backlogのバーンダウンチャート実務ガイド」で進捗を実測値として追う設計を扱った。この2本はBacklogの中で完結する運用だが、実際の現場ではBacklogの外側とのつながりが必ず必要になる。ステータスが変わったらSlackに知らせたい、期限を過ぎた課題を担当者に催促したい、自社の別システムにBacklogのデータを同期したい、といった要求である。

「Jiraの自動化ルール実務ガイド」では、トリガー・条件・アクションという3つの部品を1つのフローとして組み立てるJira Automationの仕組みを扱った。Backlogには、これに相当する単一の自動化エンジンは存在しない。その代わりに、メール通知・Webhook・Slack連携・APIという4つの独立した部品が用意されており、どれを組み合わせるかを利用者側で設計する必要がある。この記事は、Backlog公式ヘルプセンター、Backlog Developer API、Backlog公式ブログの一次情報にもとづき、この4部品の仕様と、外部ツール連携・督促の設計手順を整理する。

この記事の編集基準

本記事にアフィリエイトリンク・紹介料・掲載料は一切ない。仕様の記述は、Backlog Enterprise版ユーザーガイド（backlog.com/ja/enterprise-help）、Backlog Developer API公式ドキュメント（developer.nulab.com/docs/backlog）、Backlog公式ブログ・ヌーラボ公式プレスリリース（backlog.com/ja/blog、nulab.com/ja/press）で確認できた範囲に限定している。

4つの部品の役割分担

設計に入る前に、4つの部品がそれぞれ何を担うのかを整理する。起点になるのはいずれも「Backlog内で発生したイベント」だが、送信先・双方向性・設定の単位が異なる。

*出典：Backlog公式ヘルプセンター・Backlog Developer API・Backlog公式ブログ（2026年9月14日確認、末尾に一覧）。*

メール通知：全体設定とプロジェクト毎設定の2層

Backlogのメール通知は、個人設定内の「メール設定」で受け取るタイミングを調整する。課題の追加や終了時など、どの操作で通知を受け取るかをチェックボックスで選び、メールの件名から「新規」「コメント」「完了」「担当者変更」といった状態情報を外す設定もできる。件名を簡潔にすると、Gmailでは同じ課題に関するメールが1つのスレッドにまとまる。

この全体設定とは別に、プロジェクト毎の設定として「プロジェクトレポート」がある。プロジェクトレポートは1日1回配信され、今日が期限日の課題と期限を過ぎた課題の両方を含む。この日次レポートが、Backlogに標準で備わっている督促の仕組みにあたる。全体設定でメール受信そのものがオフになっていると、プロジェクトレポートも送信されない。

見落としやすい仕様がもう1つある。設定されているメールアドレス宛のメールが「宛先不明」として返ってきた場合、Backlogは該当ユーザーの「メールを受信する」設定を自動的にオフへ切り替える。異動でメールアドレスが変わった担当者がある日から急に通知を受け取れなくなっていた、という状況の原因はここにあることが多い。督促の運用を日次プロジェクトレポートに頼るなら、メールアドレスの有効性を定期的に確認する運用も合わせて必要になる。

Webhook：イベント駆動で外部URLへ送信する仕組み

Webhookは、課題の追加やコメントの投稿といったイベントが発生したときに、指定したURLへHTTP POSTでリアルタイムに情報を送信する機能である。データはJSON形式で送信され、共通部分を除くとイベントごとに含まれる属性が異なる。

URLには制約がある。指定できるのはBacklogのサーバーからアクセス可能なURLに限られ、イントラネット内のサーバーやプライベートIPアドレス（192.168.x.xなど）は指定できない。送信されるデータにはコミットメッセージやメールアドレスといった機微な情報が含まれ得るため、URLはHTTPSにすることが推奨されている。

Webhookの設定手順とテスト送信

Webhookは、プロジェクトのWebhook一覧画面から「Webhookを追加する」を選び、Webhook名・WebHook URL・通知するイベントの3つを入力して登録する。登録しただけでは動作を確認できないため、実行テストの項目で送信するイベントの種別を選び、実行ボタンを押すことでテストデータを実際に送信できる。テスト結果は送信履歴で確認する。

この構成から分かるとおり、Webhookはあくまでイベント駆動である。「毎朝9時に期限超過課題を集計して送る」といった時刻起点の実行はWebhookの守備範囲に含まれない。時刻起点の処理が要る場合は、後述するAPIを外部のスケジューラから定期的に呼び出す設計に切り替える必要がある。

Slack連携：プロジェクト単位のネイティブ機能

SlackはBacklogが個別に機能を拡張してきたネイティブ連携である。Webhookのような汎用URL送信ではなく、Slack側からBacklogの課題を操作できる点が最大の違いになる。この機能は複数回にわたって拡張されており、それぞれの追加時期は次のとおりである。

*出典：Backlog公式ブログ・ヌーラボ公式プレスリリース（2026年9月14日確認、末尾に一覧）。*

WebhookとSlack連携、どちらを使うか

連携先がSlackであれば、Slack連携を先に検討するべきである。通知を受け取るだけでなく、状態変更やコメント追加といった操作までSlack上で完結でき、/backlog linkでチャンネルとプロジェクトの紐づけも自分たちで確認できる。汎用のWebhookでSlackへ送る設計を自作するより、設定の負担が小さい。

一方、連携先がSlack以外のチャットツールや、自社で運用しているシステム、BIツールへのデータ同期である場合は、Webhookが唯一の選択肢になる。BacklogのWebhookはURLを指定するだけの汎用設計であるため、受け側さえJSONを解釈できれば連携先を選ばない。

API：認証方式と権限体系

APIキーの発行は、個人設定内の「API」から登録ボタンを押すことで行う。発行時にはメモを添えられ、不要になったキーは一覧から削除して無効化できる。Backlog APIは、issues・Wikiページ・ファイルの取得と更新、プロジェクトとユーザーの管理に対応し、ブラウザからのAjaxリクエストに使うCORSにも対応している。

認証方式は2種類ある。APIキー方式は、クエリパラメータ（?apiKey=キーの値）またはリクエストヘッダー（Backlog-API-Key）にキーを付与するだけの簡便な方式である。OAuth2.0方式は、OAuth 2.0の認可コードグラント（Authorization Code Grant）にもとづき、事前のアプリケーション登録が必要になる。アクセストークンの有効期限は3600秒（1時間）で、リフレッシュトークンを使って更新し、APIの呼び出しにはAuthorization: Bearerヘッダーを使う。

権限体系は、APIキー方式・OAuth2.0方式のどちらでも共通で、Administrator・Project Administrator・Member・Guestの4段階がある。MemberとGuestには、制限なし（No restriction）・課題の追加のみ（Add issue only）・閲覧のみ（View only）という追加の制限を設定でき、APIキーは発行したユーザー本人の権限をそのまま引き継ぐ。管理者権限を持つ個人アカウントでAPIキーを発行すると、そのキーは管理者と同じ範囲の操作ができてしまうため、外部連携専用のアカウントを用意し、必要な権限だけを与えたうえでそのアカウントからキーを発行する設計のほうが、権限の見通しを保ちやすい。

APIのレート制限：カテゴリ別・ユーザー単位・分単位

Backlog APIには利用制限があり、ユーザー単位・分単位で、APIの種類ごとに4つのカテゴリに分けて計測される。読み込み（Search・Icon以外のGETリクエスト）、更新（POST・PATCH・DELETEリクエスト）、検索（課題一覧・Wikiページ一覧などの検索系API）、アイコン取得（ロゴ・ユーザーアイコン・プロジェクトアイコン等）の4種類であり、無料プランと有料プランで割り当てが異なる。

制限が導入されたのは2021年1月25日で、一部ユーザーからの高頻度なAPIリクエストによってBacklogの機能が不安定になる障害が過去に何度か発生したことが理由とされている。新規に作成するスペースには発表日から即座に適用され、既存スペースには6か月の準備期間を経て2021年7月末から適用された。公表時点の割り当ては次のとおりである。

*出典：Backlog公式ブログ「重要なお知らせ：BacklogはAPIへの高頻度なリクエスト送信を制限します」（2021年1月25日公開、2026年9月14日確認）。現在の割り当てはGET /api/v2/rateLimitで確認できる。*

レート制限に達したときの挙動：429エラーとレスポンスヘッダー

各APIレスポンスには、X-RateLimit-Limit（1分間あたりの上限）・X-RateLimit-Remaining（残りリクエスト数）・X-RateLimit-Reset（制限がリセットされるUNIXエポック秒）の3つのヘッダーが付与される。呼び出し側は、レスポンスを受け取るたびにこの3つの値で残数を確認できる。

上限を超えてリクエストを送ると、429 Too Many Requestsが返る。定期実行するバッチ処理をAPIで組む場合は、429を受け取った時点で処理を止め、X-RateLimit-Resetが示す時刻まで待ってから再送する設計にしておくと、制限に触れても処理全体が失敗しない。

自分のスペースの現在の割り当てを直接確認したい場合は、GET /api/v2/rateLimitを呼び出す。read・update・search・iconの4カテゴリそれぞれについて、limit（上限）・remaining（残り）・reset（リセット時刻）が返る。外部スケジューラでバッチ処理を組む前に、この値で現在の余力を確認しておくと安全である。

督促を設計する：イベント駆動と時刻起点の使い分け

ここまでの4部品を踏まえると、督促や外部通知の設計は「いつ動かしたいか」で分岐する。イベントが起きた瞬間に反応させたいのか、時刻を起点に定期実行させたいのかを先に決めることが、部品選びの起点になる。

Webhookは課題の追加やコメントなど「Backlog内で何かが起きたとき」にしか動かない。「時間が経過したとき」に動かす督促は、Webhookではなく、APIを外部のスケジューラから定期的に呼び出す設計でしか実現できない。

まとめ：1つの自動化エンジンではなく、4部品の組み合わせで設計する

「Jiraの自動化ルール実務ガイド」で見たJira Automationは、トリガー・条件・アクションを1つの画面で組み立て、Scheduledトリガーによって時刻起点の実行にも対応する。Backlogにはこれに相当する単一の仕組みがなく、メール通知・Webhook・Slack連携・APIという4つの部品それぞれの守備範囲を理解したうえで、目的に応じて組み合わせる設計が必要になる。

イベントが起きた瞬間に外部へ知らせたいならWebhookかSlack連携、時刻を起点に何かを実行したいならAPIを外部のスケジューラと組み合わせる。この境界線を先に引いておくことが、「Backlogの課題管理実務ガイド」と「Backlogのバーンダウンチャート実務ガイド」で設計した運用を、Backlogの外側までつなげる土台になる。