Webhook URL と鍵を守る
自動投稿の仕組みで守るべき秘密は2つある。Webhook URL(中の token)と、サービスアカウントの鍵ファイル(JSON)だ。どちらも、持っている人がそのスペースにメッセージを送れてしまう。
置き場所
| 実行場所 | おすすめの置き場所 | 避けたい置き方 |
|---|---|---|
| 手元 PC・サーバー | 環境変数、またはリポジトリの外に置いた権限付きのファイル(Linux なら chmod 600) | スクリプトへの直書き、crontab への直書き |
| Apps Script | スクリプト プロパティ(PART 04) | コードへの直書き(プロジェクトを共有すると一緒に見える) |
| AWS Lambda | Parameter Store の SecureString、または Secrets Manager | Lambda の環境変数に平文で入れる(関数の設定を見られる人全員に見える) |
| Google Cloud(Cloud Run など) | Secret Manager。Chat API なら鍵を作らず、実行環境にサービスアカウントを割り当てる | 鍵ファイルをコンテナーイメージに含める |
Git のリポジトリに紛れ込むのを防ぐには、.gitignore に鍵ファイルや .env を入れておくのに加えて、コミット前に秘密情報を検出するツール(gitleaks など)を使うと安心だ。Webhook URL は形が決まっているので、手作業でも次のように探せる。
# リポジトリ内に Webhook URL が残っていないか確認する
git grep -nE 'chat\.googleapis\.com/v1/spaces/[^/]+/messages\?key=' -- .漏れたときの対応
| 漏れたもの | すぐやること |
|---|---|
| Webhook URL | スペースの「アプリとインテグレーション」でその Webhook を 削除 し、新しく作り直して URL を差し替える。token だけを再発行することはできないので、作り直しが唯一の手段になる |
| サービスアカウントの鍵 | Google Cloud コンソールのサービスアカウントの「キー」で、その鍵を 無効化または削除 し、新しい鍵を発行して差し替える。同じサービスアカウントの他の鍵が不要なら一緒に削除する |
どちらも、差し替えるまでの間は送信が止まる。どのスクリプトがどの URL・鍵を使っているか を一覧にしておくと、差し替えの抜け漏れを防げる(チェックリスト 参照)。
429 に備えたリトライ
PART 01 で触れたとおり、書き込みは1スペースあたり1秒1回までで、超えると 429 が返る。障害時にアラームが一斉に鳴る、ループで連続投稿する、といった場面で起きる。公式ドキュメントは、時間あたりの上限やネットワークのエラーに対して 指数バックオフ(待ち時間を倍々に延ばしながら再試行する方法)を推奨している。
"""Webhook への投稿を、429 や一時的なエラーのときだけ再試行する"""
import os
import random
import time
import requests
WEBHOOK_URL = os.environ["GCHAT_WEBHOOK_URL"]
RETRY_STATUS = {429, 500, 502, 503, 504}
def post_with_retry(payload: dict, params: dict | None = None,
max_attempts: int = 5, base: float = 1.0, cap: float = 32.0) -> dict:
for attempt in range(1, max_attempts + 1):
try:
resp = requests.post(WEBHOOK_URL, json=payload, params=params, timeout=10)
except (requests.ConnectionError, requests.Timeout):
if attempt == max_attempts:
raise
else:
if resp.status_code not in RETRY_STATUS:
resp.raise_for_status() # 400 や 403 などは再試行しても直らないので即座に例外
return resp.json()
if attempt == max_attempts:
resp.raise_for_status()
# 1, 2, 4, 8 … 秒(上限 cap 秒)に、0〜1秒のゆらぎを足して待つ
time.sleep(min(cap, base * 2 ** (attempt - 1)) + random.random())
raise RuntimeError("unreachable")ポイントは、再試行するエラーを選ぶ ことだ。400(JSON の誤り)や 403(権限がない)は何度送っても結果が変わらないので、すぐに失敗させてログに残す。待ち時間にゆらぎ(random.random())を足しているのは、複数のプロセスが同時に再試行して、また同じ瞬間にぶつかるのを避けるためだ。
⚠️ タイムアウト後の再試行は二重投稿になることがある
タイムアウトは「届かなかった」とは限らない。メッセージは作成されたのに応答だけが返ってこなかった場合、再試行すると同じ通知が2通届く。通知なら2通届いても実害は小さいが、気になる場合は Chat API で messageId を指定して投稿する(PART 05)。同じ messageId での2回目の作成はエラー(409)になるので、二重投稿を防げる。
そもそも429を起こしにくくする工夫も効く。
- まとめて1通にする:10件のアラームを10通送るのではなく、数秒ためてから「10件発生」の1通にする
- 連続投稿の間隔をあける:ループで送るときは、1通ごとに1.1秒ほど
time.sleep()を入れる - スペースを分ける:上限はスペースごとなので、大量に流れる通知は別のスペースに分ける
長いメッセージを分割する
1つのメッセージはテキストとカードを合わせて 32,000 バイトまで だ。日本語は UTF-8 で1文字3バイトになることが多いので、およそ1万文字が上限の目安になる。ログやリソース一覧を貼る通知では、行の切れ目で分割して複数のメッセージにする。
def split_text(text: str, limit_bytes: int = 30_000) -> list[str]:
"""行の切れ目で、UTF-8 のバイト数が limit_bytes 以下になるよう分割する"""
chunks, current, size = [], [], 0
for line in text.splitlines(keepends=True):
n = len(line.encode("utf-8"))
if current and size + n > limit_bytes:
chunks.append("".join(current))
current, size = [], 0
current.append(line) # 1行だけで上限を超える行はそのまま(必要なら切り詰める)
size += n
if current:
chunks.append("".join(current))
return chunks
# 例:分割したものを同じスレッドに順番に送る(間隔をあけて 429 を避ける)
# for i, chunk in enumerate(split_text(long_log), 1):
# post_text(f"({i}) ```\n{chunk}```", thread_key="report-2026-10-31")
# time.sleep(1.1)上限ちょうどではなく 30,000 バイトにしているのは、JSON のキーや装飾の記号の分の余裕を持たせるためだ。とはいえ、1万文字のログを Chat で読む人はいない。Chat には要約と件数だけを送り、全文は S3 やドライブに置いてリンクを貼る 形にできないか、先に検討したい。
よくあるエラーと対処
エラーの応答には、数値の code と、文字列の status・message が入っている。公式ドキュメントは、message の文言は予告なく変わることがあるので、処理の分岐には数値の code を使うよう勧めている。
{
"error": {
"code": 400,
"message": "Invalid JSON payload received. Unknown name \"txt\" at 'message': Cannot find field.",
"status": "INVALID_ARGUMENT"
}
}| コード | 主な原因 | 対処 |
|---|---|---|
400 INVALID_ARGUMENT | JSON の書き間違い、キー名の誤り(txt など)、カードの構造の誤り、messageId の形式違い | message に出ている項目名を確認する。再試行しない |
401 UNAUTHENTICATED | (Chat API)鍵が無効・削除済み、スコープの指定漏れ | 鍵とスコープ chat.bot を確認する |
403 PERMISSION_DENIED | 組織が Webhook / Chat アプリを禁止した、アプリがスペースのメンバーでない、URL の token が欠けている | 管理者設定とスペースのメンバーを確認する。bash では URL のクォート漏れも疑う |
404 NOT_FOUND | Webhook またはスペースが削除された、スペース名の誤り、Chat API の構成が保存されていない、書き換え対象のメッセージがない | URL・スペース名・messageId を確認する |
409 ALREADY_EXISTS | (Chat API)同じ messageId のメッセージがすでにある | 二重投稿の防止として正常に扱うか、ID の付け方を見直す |
429 RESOURCE_EXHAUSTED | 1スペース1秒1回の書き込み上限を超えた | 指数バックオフで再試行する。まとめて送る |
500 / 503 | Google 側の一時的な障害 | 指数バックオフで再試行する |
同じ原因でも状況によって返るコードが違うことがあるので、表は「最初に疑う場所」として使ってほしい。Chat API の場合は、構成画面で「エラーを Logging に記録」を有効にしておくと、Cloud Logging にエラーの詳細が残る。
組織の管理者設定
Webhook や Chat アプリが使えるかどうかは、Google Workspace の管理コンソールの設定で決まる。管理者に相談するときは、次の場所を伝えると話が早い(画面の表記は変わることがある)。
- アプリ → Google Workspace → Google Chat の中の、Chat 用アプリに関する設定
- 「ユーザーに受信 Webhook の追加と使用を許可する」:Webhook を使うのに必要
- 「ユーザーに Chat 用アプリのインストールを許可する」:Chat API で作ったアプリをスペースに追加するのに必要
設定は組織部門ごとに変えられるので、「運用チームの組織部門だけ許可する」といった相談もできる。管理者の立場から見ると、Webhook は URL さえあれば誰でも投稿できる仕組みなので、誰が・どのスペースに・何の目的で作るのか を説明できるようにしておくと許可が得やすい。
読まれる通知にするための設計
技術的に正しく送れても、通知が多すぎると誰も読まなくなり、本当に大事なアラームを見落とす。筆者が運用しながら決めたルールを挙げておく。
| ルール | 具体的には |
|---|---|
| 重要度でスペースを分ける | 「要対応」(障害・失敗)と「情報」(成功・定期レポート)を別スペースにし、要対応だけ通知をオンにしてもらう |
| 正常は まとめて、異常は すぐに | 成功したバッチは1日1回のまとめに入れ、即時に送るのは失敗だけにする |
| スレッドでまとめる | threadKey を日付やアラーム名にして、スペースの一覧が流れないようにする(PART 02) |
| 全員メンションは障害時だけ | <users/all> は本番障害のときだけに使い、日常の通知では使わない |
| 次にやることを書く | 「失敗しました」だけでなく、ログや手順書へのボタンを付ける(PART 03) |
| 送り元を名乗る | Webhook 名・アプリ名で、どの仕組みから来た通知かわかるようにする |
💡 「来ない」ことに気づける仕組みを作る
通知の仕組みそのものが止まると、静かなので誰も気づかない。毎朝のコスト投稿のような定期投稿は「仕組みが生きている」合図にもなる。Lambda なら、関数の Errors メトリクスに CloudWatch アラームを付けておき、投稿処理そのものの失敗も別の経路(メールなど)で知らせると安心だ。
運用チェックリスト
- Webhook URL・鍵ファイルがコードやリポジトリに含まれていない
- どのスクリプトがどの Webhook / 鍵を使っているかの一覧がある
- Webhook 名・アプリ名で送り元がわかる
- 429 と 5xx だけを指数バックオフで再試行している
- 連続投稿の間隔をあけている、または1通にまとめている
- 長いログは要約にし、全文はリンクで見せている
- 「要対応」と「情報」のスペースを分けている
- 通知の仕組み自体が止まったときに気づける
- 漏えい時の差し替え手順(Webhook の作り直し・鍵の無効化)を決めてある
シリーズのまとめ
6回にわたって、Google Chat への自動投稿を見てきた。要点を振り返っておく。
| 回 | 持ち帰ってほしいこと |
|---|---|
| PART 01 | 入口は Webhook と Chat API の2つ。まず Webhook で始め、必要になったら移る |
| PART 02 | URL に JSON を POST するだけ。Windows PowerShell 5.1 は UTF-8 のバイト列で送る。threadKey でまとめる |
| PART 03 | cardsV2 は関数で部品化する。カード内の書式は HTML タグ。Webhook のボタンはリンクだけ |
| PART 04 | 情報のある場所の近くで動かす。Apps Script・タスクスケジューラ・Lambda を使い分ける |
| PART 05 | Chat API なら書き換え・削除・複数スペース。書式の既定が Markdown である点に注意 |
| PART 06 | 秘密を守り、429 に備え、読まれる量に絞る |
通知に載せる AWS の情報の取り方は、boto3 シリーズ(Python)と Steampipe シリーズ(SQL)で詳しく扱っている。棚卸しの結果やコストを、この連載の仕組みで毎朝 Chat に流す、という組み合わせもぜひ試してほしい。