Google Chat Webhookの使い方｜作成・カード・スレッド・エラー対策

Expert Q&A

Webhookを作る前に確認すること

湯田英也SakuraAI株式会社 代表 / ソフトウェアエンジニア

Q. Webhookで最初に自動化するなら何ですか？

A. 結果が明確で、通知先が固定された処理です。バッチ完了、監視アラート、フォーム受付、日次集計が向いています。承認や問い合わせ対応から始めない方がよいです。

Q. カードに承認ボタンを付ければ承認できますか？

A. Webhookはクリックイベントを受け取れません。確認画面を開くリンクは置けますが、承認で状態を更新するならChatアプリが必要です。表示できることと操作できることを分けます。

Q. Webhook運用で最も多い事故は？

A. URLの漏えいと通知の連打です。URLをログやコードへ残さず、同じスペースへ複数システムが送る場合はキューで流量を制御します。

Google Chatへシステム通知を送りたいだけなら、最初からChatアプリを開発する必要はありません。受信Webhookをスペースへ登録し、発行されたURLへJSONをPOSTすれば通知できます。

仕組みは単純ですが、作成手順だけで本番運用を始めると、URL漏えい、通知重複、429エラー、アラートの大量投稿が起きます。Webhookは簡単に作れるからこそ、止め方と失敗時の扱いを先に決めます。

Google Chat Webhookとは

受信Webhookは、外部サービスから特定のGoogle Chatスペースへ非同期の一方向通知を送る仕組みです。Webhookごとに登録先スペースが決まり、そのURLを使って別のスペースへ投稿することはできません。

WebhookはGoogle Workspace Marketplaceへ公開する仕組みでもありません。組織内で複数の利用者やスペースへ配布する製品にしたい場合は、Chatアプリを検討します。

Webhookが向く用途・向かない用途

Webhookの作成手順

Google公式の手順では、ブラウザ版Google Chatから設定します。

1. 通知先のスペースを開く
2. スペース名のメニューからアプリとインテグレーションを開く
3. Webhookを追加する
4. 用途が分かる名前とアイコンを設定する
5. 発行されたWebhook URLをシークレット管理へ保存する

Webhookを追加する項目が表示されない場合は、組織で受信Webhookの利用が許可されているか、管理者へ確認します。モバイルアプリからはWebhookを構成できません。

テキストメッセージを送る

最小の通知は、text を持つJSONをPOSTします。

curl -X POST "$GOOGLE_CHAT_WEBHOOK_URL" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{"text":"[INFO] 日次処理が完了しました"}'

GOOGLE_CHAT_WEBHOOK_URL はシークレット管理から実行時に渡します。コマンド履歴、CIログ、エラー出力へURLそのものを表示しないようにします。

通知文に入れる7項目

通知にシステムのログ全文を貼る必要はありません。エラーの要点と追跡IDを載せ、権限を設定した監視画面やログへリンクします。

カード形式は情報整理とリンクに使う

カード形式を使うと、見出し、項目、画像、ボタンを構造化できます。Webhookは一方向なので、ボタンは外部ページを開くリンクとして使います。

{
  "cardsV2": [
    {
      "cardId": "monitoring-alert",
      "card": {
        "header": {
          "title": "監視アラート",
          "subtitle": "ALERT-2048"
        },
        "sections": [
          {
            "widgets": [
              {
                "decoratedText": {
                  "topLabel": "状態",
                  "text": "要確認"
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "監視画面を開く",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/alerts/2048"
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

threadKeyで同じ案件をまとめる

受信Webhookは、thread.threadKey と messageReplyOption を使ってスレッドを開始・返信できます。同じ障害、案件、バッチ実行を1つのスレッドへまとめると、スペースの流量を減らせます。

{
  "text": "ALERT-2048: 応答時間が正常範囲へ戻りました",
  "thread": {
    "threadKey": "alert-2048"
  }
}

Webhook URL側の messageReplyOption は、スレッドがない場合に新規作成するか、送信を失敗させるかを制御します。

threadKey は通知文から毎回生成せず、アラートIDや案件IDから安定して作ります。キーが変わると、同じ事象が別スレッドへ分かれます。

Apps Scriptから送信する

Apps Scriptは、Gmail、Googleフォーム、スプレッドシート、Calendarなどを起点にWebhookへPOSTする実行基盤として使えます。

function notifyChat(message) {
  const url = PropertiesService.getScriptProperties()
    .getProperty("GOOGLE_CHAT_WEBHOOK_URL");

  const response = UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json; charset=UTF-8",
    payload: JSON.stringify({ text: message }),
    muteHttpExceptions: true,
  });

  const status = response.getResponseCode();
  if (status < 200 || status >= 300) {
    throw new Error(`Google Chat webhook failed: HTTP ${status}`);
  }
}

スクリプトプロパティはコード直書きより安全ですが、誰がプロジェクトとプロパティを閲覧・編集できるかも確認します。実行ログへURLや通知本文を不用意に出力しません。

URLを秘密情報として管理する

Webhook URLには key と token が含まれます。パスワードと同じように扱います。

Webhook URLを1本だけ作り、すべてのシステムで共有すると、漏えい時に影響元を特定できません。用途や送信元ごとに分けると、個別に停止できます。

レート制限と送信キュー

2026年6月28日時点のGoogle公式情報では、同じスペースへのメッセージ書き込みは原則1秒あたり1回で、受信Webhookには追加制限も適用されます。複数Webhookの送信量は同じスペースで共有されます。

すべてのイベントを即時に1件ずつ送るのではなく、緊急アラートは即時、定期結果は集約、回復通知は同じスレッドというように分けます。

再試行で重複投稿しない設計

送信元がタイムアウトした場合、Chat側では投稿済みでも、送信元は失敗と判断することがあります。無条件に再送すると同じ通知が増えます。

Webhookのレスポンスにはメッセージ全体が含まれず、name と thread.name が中心です。Webhookだけを正本にせず、送信元側にイベントと状態を残します。

通知疲れを防ぐルール

成功通知をすべて流すと、本当に見るべき失敗が埋もれます。通知件数ではなく、未対応、確認時間、誤通知を測ります。

WebhookからChatアプリへ移る基準

次の要件が出たら、Webhookへ機能を足すのではなくChatアプリを検討します。

• ユーザーのメッセージやメンションへ応答したい
• ボタンで担当引受、承認、差戻しを処理したい
• ダイアログで入力を受け付けたい
• 利用者ごとに権限を変えたい
• 動的に複数スペースやDMへ送信したい
• メッセージの更新・削除やメンバー管理が必要

Webhook・Chat API・Chatアプリ・Apps Scriptの全体像はGoogle Chat APIとは、対話型の設計はGoogle Chat Bot開発の設計パターンで解説しています。

導入手順

1. 通知専用でよいか確認する

ユーザー操作を受け取らず、通知先が固定スペースであることを確認します。承認や対話が必要ならChatアプリを選びます。

2. テスト用Webhookで送信する

本番スペースへ直接作らず、テストスペースでテキスト、カード、エラーを確認します。URLは最初からシークレット管理へ置きます。

3. イベントIDとメッセージ形式を決める

種別、イベントID、発生元、要点、状態、担当、期限、正本リンクを固定します。同じ事象をまとめるならthreadKeyも決めます。

4. キュー・再試行・重複防止を作る

429と一時障害は指数バックオフ、400系は停止、最終失敗は失敗キューへ残します。再送前にイベントIDの処理状態を確認します。

5. 漏えい・廃止時の停止手順を試す

Webhook削除、シークレット更新、送信元停止、スペース変更の手順を確認します。所有者不明のWebhookを作りません。

6. 指標を見て運用する

よくある失敗

SakuraAIで支援できること

SakuraAIは、Google Chat Webhookの作成だけでなく、通知対象、メッセージ、スレッド、送信キュー、再試行、重複防止、シークレット管理、監視、停止手順まで設計します。

通知だけならWebhookで小さく始め、ユーザー操作や動的な権限が必要になった時点でChatアプリとChat APIへ移行します。Apps Script、既存システム、Cloud実行環境も要件に合わせて選びます。

Expert Q&A

最後に湯田へ確認

湯田英也SakuraAI株式会社 代表 / ソフトウェアエンジニア

Q. Webhook導入が成功した状態とは？

A. 通知が届くだけでなく、重複せず、重要なものが埋もれず、担当者が正本へ移って対応でき、失敗時に再処理できる状態です。投稿件数の多さは成功指標ではありません。

Q. 1つのスペースへWebhookはいくつ作りますか？

A. 最低でも用途や送信元を識別できる単位に分けます。すべてを1本にすると漏えい時に全連携を止めることになります。ただし増やしすぎず、所有者と利用先を台帳で管理します。

Q. 本番前に最低限試すことは？

A. 正しい投稿、400、429、ネットワーク失敗、同一イベント再送、Webhook削除です。スレッドを使う場合は、既存キーと存在しないキーの動作も確認します。

Reviewed by

監修者: 湯田英也

SakuraAI株式会社 代表 / ソフトウェアエンジニア

Google Chatの導入・移行、Google Workspace連携、Google Chat API / Webhook / Bot、Gmail・Meet・Drive・Calendarをまたぐ業務自動化領域を監修しています。

Google公式情報、各プロダクトの仕様、実務での運用・開発観点をもとに、企業が導入判断・運用設計・自動化設計を行える内容になるよう確認しています。

GitHubLinkedInX

プロフィール