Webhook を作成する

Webhook はスペースごとに作る。通知専用のスペース(例:「AWS運用通知」)を先に作っておくと、雑談に通知が混ざらずに済む。作成は ブラウザ版の Google Chat で行う(モバイルアプリでは設定できない)。

  1. ブラウザで Google Chat を開き、投稿先のスペースに移動する
  2. スペース名の横の下向き矢印をクリックし、「アプリとインテグレーション」 を選ぶ
  3. 「Webhook を追加」 をクリックする
  4. 名前 に投稿者として表示したい名前(例:夜間バッチ)を入れる。アバターの URL は任意で、HTTPS の画像 URL を指定するとアイコンになる
  5. 保存 をクリックする
  6. 作成された Webhook の 「その他」(︙)→「リンクをコピー」 で URL をコピーする

「Webhook を追加」が押せない場合は、組織の管理者が Webhook の利用を許可していない(PART 01)。

名前は 「どの仕組みから来た通知か」がわかるもの にしておくと、後で困らない。筆者は「夜間バッチ」「AWSコスト」「CloudWatch」のように、送り元ごとに Webhook を分けている。同じスペースに複数作っても問題ない。

Webhook URL の中身

コピーした URL は次の形をしている。

Webhook 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 が欠けたリクエストになる)。

bash
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)だけだ。

レスポンス例(IDはマスク)
{
  "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 のバイト列に変換して渡すと解決する。

PowerShell
$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 $bytes

PowerShell 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 の指定を任せられる。

PowerShell / bash
pip install requests

以降の回でも使い回せるよう、送信処理を小さなモジュールにしておく。

Python(gchat_webhook.py)
"""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.py

requests は、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 と書く。これらを組み合わせると、たとえば次のような通知になる。

Python
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つのスレッドにまとめられる。

  1. メッセージの JSON に "thread": {"threadKey": "任意の文字列"} を入れる
  2. URL に messageReplyOption パラメータを付ける
  3. 2通目以降も同じ threadKey で送ると、そのスレッドへの返信になる
messageReplyOption の値同じキーのスレッドがあるときないとき
REPLY_MESSAGE_FALLBACK_TO_NEW_THREADそのスレッドに返信そのキーで新しいスレッドを作る
REPLY_MESSAGE_OR_FAILそのスレッドに返信投稿しない(エラーになる)
(付けない)毎回新しいスレッドになる(threadKey は無視される)

キーの付け方で、まとめ方を設計できる。筆者がよく使うのは次のパターンだ。

キーの例まとまり方
batch-2026-10-311日分のバッチ通知が1スレッドにまとまる
alarm-HighCPU-web同じアラームの「発報→復旧」が1スレッドに並ぶ
deploy-v1.4.21回のリリースの開始・各段階・完了をまとめる
Python
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 receivedJSON の書き間違い(末尾のカンマ、" の閉じ忘れ、キー名の誤り)。python -m json.tool msg.json で確認する
スレッドにまとまらないURL に messageReplyOption を付けていない
*太字* が太字にならない* の内側に空白がある(* 太字 *)。記号は文字に密着させる

その他のエラーは PART 06 のエラー一覧 にまとめている。

✅ 次の記事では…

PART 03 では、テキストの代わりにカード(cardsV2)を送り、見出し・ラベル付きの値・ボタンを並べた見やすい通知を作る。今回の post_message() をそのまま使う。

→ PART 03 — カードメッセージで見やすい通知を作るへ