Webhook を作成する
Webhook はスペースごとに作る。通知専用のスペース(例:「AWS運用通知」)を先に作っておくと、雑談に通知が混ざらずに済む。作成は ブラウザ版の Google Chat で行う(モバイルアプリでは設定できない)。
- ブラウザで Google Chat を開き、投稿先のスペースに移動する
- スペース名の横の下向き矢印をクリックし、「アプリとインテグレーション」 を選ぶ
- 「Webhook を追加」 をクリックする
- 名前 に投稿者として表示したい名前(例:
夜間バッチ)を入れる。アバターの URL は任意で、HTTPS の画像 URL を指定するとアイコンになる - 保存 をクリックする
- 作成された Webhook の 「その他」(︙)→「リンクをコピー」 で URL をコピーする
「Webhook を追加」が押せない場合は、組織の管理者が Webhook の利用を許可していない(PART 01)。
名前は 「どの仕組みから来た通知か」がわかるもの にしておくと、後で困らない。筆者は「夜間バッチ」「AWSコスト」「CloudWatch」のように、送り元ごとに Webhook を分けている。同じスペースに複数作っても問題ない。
Webhook URL の中身
コピーした URL は次の形をしている。
https://chat.googleapis.com/v1/spaces/AAAAxxxxxxx/messages?key=AIzaSy...&token=Xyz123...| 部分 | 意味 |
|---|---|
spaces/AAAAxxxxxxx | 投稿先スペースの ID。Chat API で使う「スペース名」と同じもの |
key= | Webhook 共通の API キー。どの Webhook でも同じ値になる |
token= | Webhook ごとに固有の秘密の値。これを知っていれば誰でもそのスペースに投稿できる |
⚠️ URL はパスワードと同じ扱いにする
URL が漏れると、第三者がそのスペースに好きなメッセージを送れてしまう。スクリプトに直書きして Git に上げる、チケットに貼る、といった事故が一番多い。この記事では環境変数 GCHAT_WEBHOOK_URL から読む形にそろえる。保管方法と漏れたときの対応は PART 06 で扱う。
curl で最初の1通を送る(Linux / macOS / WSL)
投稿は、URL に {"text": "..."} という JSON を POST するだけだ。URL に & が含まれるので、必ずクォートで囲む(囲まないとシェルが & で区切ってしまい、token が欠けたリクエストになる)。
export GCHAT_WEBHOOK_URL='https://chat.googleapis.com/v1/spaces/AAAAxxxxxxx/messages?key=...&token=...'
curl -sS -X POST "$GCHAT_WEBHOOK_URL" \
-H 'Content-Type: application/json; charset=UTF-8' \
-d '{"text": "Webhook からのテスト投稿です 👋"}'成功すると、作成されたメッセージの情報が返る。Webhook の応答に含まれるのは、メッセージの名前(name)とスレッドの名前(thread.name)だけだ。
{
"name": "spaces/AAAAxxxxxxx/messages/abcDEF123.abcDEF123",
"thread": {
"name": "spaces/AAAAxxxxxxx/threads/abcDEF123"
}
}PowerShell から送る(日本語の文字化けに注意)
Windows では PowerShell の Invoke-RestMethod を使うのが手軽だ。ただし、Windows に標準で入っている Windows PowerShell 5.1 では、そのまま送ると日本語が「????」に化ける。5.1 は文字列の本文を UTF-8 として送らないためで、本文をあらかじめ UTF-8 のバイト列に変換して渡すと解決する。
$env:GCHAT_WEBHOOK_URL = 'https://chat.googleapis.com/v1/spaces/AAAAxxxxxxx/messages?key=...&token=...'
$body = @{ text = "PowerShell からのテスト投稿です。日本語も表示されます。" } | ConvertTo-Json -Compress
$bytes = [System.Text.Encoding]::UTF8.GetBytes($body) # ← 5.1 ではこの変換が必須
Invoke-RestMethod -Method Post -Uri $env:GCHAT_WEBHOOK_URL `
-ContentType 'application/json; charset=UTF-8' -Body $bytesPowerShell 7(pwsh)は既定で UTF-8 を送るので、文字列のまま -Body $body と渡しても化けない。どちらで動くかわからないスクリプトなら、上のようにバイト列で渡す書き方にしておけば両方で動く。
💡 Windows で curl を使うなら JSON はファイルに書く
Windows 11 には curl.exe も入っているが、PowerShell やコマンドプロンプトでは JSON の中の " のエスケープが面倒になる。JSON を UTF-8 で保存したファイル(例:msg.json)にして curl.exe -X POST "$env:GCHAT_WEBHOOK_URL" -H "Content-Type: application/json; charset=UTF-8" --data-binary "@msg.json" とすると確実だ。Windows PowerShell 5.1 では curl が Invoke-WebRequest の別名になっているので、curl.exe と拡張子まで書く。
Python から送る
スクリプトに組み込むなら Python が扱いやすい。requests の json= 引数を使えば、JSON への変換と Content-Type の指定を任せられる。
pip install requests以降の回でも使い回せるよう、送信処理を小さなモジュールにしておく。
"""Google Chat の Incoming Webhook に投稿する小さなモジュール"""
import os
import requests
WEBHOOK_URL = os.environ["GCHAT_WEBHOOK_URL"]
def post_message(payload: dict, thread_key: str | None = None, timeout: float = 10.0) -> dict:
"""payload({"text": ...} や {"cardsV2": [...]})を投稿し、レスポンスの JSON を返す。
thread_key を渡すと、同じキーのスレッドに返信する(なければ新しいスレッドを作る)。
"""
params = {}
if thread_key:
payload = {**payload, "thread": {"threadKey": thread_key}}
params["messageReplyOption"] = "REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
resp = requests.post(WEBHOOK_URL, json=payload, params=params, timeout=timeout)
resp.raise_for_status() # 4xx / 5xx なら例外にする
return resp.json()
def post_text(text: str, thread_key: str | None = None) -> dict:
return post_message({"text": text}, thread_key=thread_key)
if __name__ == "__main__":
print(post_text("Python からのテスト投稿です。"))python gchat_webhook.pyrequests は、URL にすでに付いている key・token を残したまま params のパラメータを追加してくれるので、URL を自分で組み立て直す必要はない。
文字の装飾・リンク・メンション
Webhook で送るテキストは、既定で Google Chat 独自の記法 で解釈される。Markdown に似ているが、太字が * 1つである点が違う。
| 表示 | 書き方(Webhook の既定) | 例 |
|---|---|---|
| 太字 | *文字* | *失敗* しました |
| 斜体 | _文字_ | _prod_ 環境 |
| 取り消し線 | ~文字~ | ~旧手順~ |
| 等幅(インライン) | `文字` | `i-0123abcd` |
| 等幅(ブロック) | ``` で前後を囲む | ログの抜粋など |
| 箇条書き | 行頭に * または - | - web-01: OK |
| 引用 | 行頭に > | >エラーメッセージ |
| リンク(表示文字を指定) | <URL|表示文字> | <https://example.com/log|ログを開く> |
| 全員へのメンション | <users/all> | <users/all> 本番障害です |
| 特定ユーザーへのメンション | <users/ユーザーID> | <users/123456789012345678901> |
改行は JSON の文字列の中で \n と書く。これらを組み合わせると、たとえば次のような通知になる。
from gchat_webhook import post_text
post_text(
"❌ *夜間バッチ:失敗*\n"
"- ジョブ: `daily-aggregate`\n"
"- 環境: _prod_\n"
"- 終了コード: `2`\n"
"<https://example.com/jobs/daily-aggregate/logs|ログを開く>"
)⚠️ Markdown の **太字** は Webhook では効かない
Chat API で新しく作った Chat アプリは、既定の書式が標準の Markdown(**太字**、[表示文字](URL))になっている。一方 Webhook の既定は Chat 独自の記法だ。Webhook 用に書いたメッセージを Chat API に流用すると表示が変わるので、PART 05 で書式を指定する方法を確認してほしい。
特定のユーザーへのメンションには、メールアドレスではなく 数字のユーザー ID が必要になる。ID は Chat API でスペースのメンバー一覧を取ると調べられる(PART 05)。全員へのメンション <users/all> は、スペースの全員に通知が飛ぶので、本当に急ぎのときだけに絞りたい。
スレッドにまとめて投稿する
通知のたびに新しいスレッドができると、スペースがすぐに流れてしまう。threadKey を使うと、同じキーを持つメッセージを1つのスレッドにまとめられる。
- メッセージの JSON に
"thread": {"threadKey": "任意の文字列"}を入れる - URL に
messageReplyOptionパラメータを付ける - 2通目以降も同じ
threadKeyで送ると、そのスレッドへの返信になる
messageReplyOption の値 | 同じキーのスレッドがあるとき | ないとき |
|---|---|---|
REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD | そのスレッドに返信 | そのキーで新しいスレッドを作る |
REPLY_MESSAGE_OR_FAIL | そのスレッドに返信 | 投稿しない(エラーになる) |
| (付けない) | 毎回新しいスレッドになる(threadKey は無視される) | |
キーの付け方で、まとめ方を設計できる。筆者がよく使うのは次のパターンだ。
| キーの例 | まとまり方 |
|---|---|
batch-2026-10-31 | 1日分のバッチ通知が1スレッドにまとまる |
alarm-HighCPU-web | 同じアラームの「発報→復旧」が1スレッドに並ぶ |
deploy-v1.4.2 | 1回のリリースの開始・各段階・完了をまとめる |
from datetime import date
from gchat_webhook import post_text
key = f"batch-{date.today():%Y-%m-%d}"
post_text("*日次集計* 開始しました", thread_key=key)
# ... 処理 ...
post_text("*日次集計* 完了しました(12,480件)", thread_key=key)スレッドの最初のメッセージには 一覧で見たときに内容がわかる見出し(「10/31 の夜間バッチ」など)を書いておくと、スペースを開いた人がスレッドを開かずに状況をつかめる。
つまずきやすい点
| 症状 | 原因と対処 |
|---|---|
| 日本語が「????」になる | Windows PowerShell 5.1 で文字列のまま送っている。UTF-8 のバイト列にして送る(上記) |
| bash で 400 や 403 が返る | URL をクォートしていないため &token=... が切れている。URL を '...' か "..." で囲む |
400 Invalid JSON payload received | JSON の書き間違い(末尾のカンマ、" の閉じ忘れ、キー名の誤り)。python -m json.tool msg.json で確認する |
| スレッドにまとまらない | URL に messageReplyOption を付けていない |
*太字* が太字にならない | * の内側に空白がある(* 太字 *)。記号は文字に密着させる |
その他のエラーは PART 06 のエラー一覧 にまとめている。
✅ 次の記事では…
PART 03 では、テキストの代わりにカード(cardsV2)を送り、見出し・ラベル付きの値・ボタンを並べた見やすい通知を作る。今回の post_message() をそのまま使う。