WebhookとはAPIとの違いと仕組み・使うときの注意点
Webhookとは、特定のイベントが起きたときに、相手のURLへ自動で通知を送る仕組みです。APIのポーリングとの違い、受信側の作り方、署名の検証や再送への備えなど注意点を整理します。
公的機関・公式資料などの一次情報と照合して作成しています。このサイトについて
Webhookとは
Webhook とは、あるサービスで特定のイベント（出来事）が起きたときに、あらかじめ登録した別のサーバーのURLへ、自動で通知を送る仕組みです。GitHub の公式ドキュメントでは、特定のイベントが発生したときに外部のWebサーバーへ自動で通知を配信する仕組みと説明され、データが発生した時点で、すぐに受け取れる点が特徴とされています。
たとえば、「プルリクエストが作られたら、チャットに通知する」「フォームが送信されたら、別のシステムに登録する」といった連携で使われます。SaaS同士をつなぐ自動化の基本部品のひとつで、API と合わせて理解しておくと、連携の仕組みが見通せます。
基本（仕組みと API との違い）
GitHub のドキュメントに沿って、仕組みを手順で示します。
| 手順 | 内容 |
|---|---|
| 1. 登録 | Webhook を作るとき、通知を受け取るURLと、通知してほしいイベントを指定する |
| 2. 発生 | 指定したイベントが起きる |
| 3. 送信 | サービス側が、指定のURLに、イベントのデータを含むHTTPリクエストを送る |
| 4. 受信と処理 | 受け取った側のサーバーが、内容に応じて処理する |
API を使った方法との違いを整理します。
| 観点 | API（ポーリング） | Webhook |
|---|---|---|
| 動き | 受け取る側が、定期的に「変化はあるか」と問い合わせる | 変化が起きたとき、サービス側から通知が来る |
| 反映の速さ | 問い合わせの間隔に依存する | ほぼリアルタイムにできる |
| 無駄な通信 | 変化がなくても問い合わせる | 変化があったときだけ通信する |
| 受け取る側の準備 | 呼び出す処理を書く | 外部から受け取れるURLを用意する |
公式ドキュメントでは、Webhook は API のポーリングより少ない労力と資源で運用でき、拡張しやすく、ほぼリアルタイムの更新を実現できると説明されています。
Webhookの具体例
連携の例です。
| 目的 | きっかけのイベント | 受け取る側の処理 |
|---|---|---|
| 開発の通知 | プルリクエストの作成 | チャットに知らせる |
| 自動テスト | コードの送信（push） | テストを実行する自動化の仕組みを起動する |
| 問い合わせの共有 | フォームの送信 | 担当者のチャンネルに投稿し、台帳に登録する |
| 公開の自動化 | 本流への変更の取り込み | サーバーへの配置を始める |
ポーリングとの通信量の違いの例です。5分ごとに変化を確認するAPIの呼び出しは、1日に 24 × 60 ÷ 5 = 288 回です。しかし、実際に変化があるのが1日に3回なら、285回は無駄な呼び出しです。Webhook なら、変化があった3回の通知だけで済みます。
Webhookの実践ステップ
- 連携したい出来事（イベント）と、その後に自動で行いたい処理を決める。
- 提供元の公式ドキュメントで、利用できるイベントの種類と、送られるデータの形式を確認する。
- 通知を受け取るURLを用意する（自前のサーバー、または連携用のサービス）。
- Webhook を登録し、テスト用のイベントで、受信を確認する。
- 受け取ったデータが、本当に提供元から来たものかを、検証する仕組みを入れる。
- 失敗したときの再送や、二重の通知への対応を決める。
- 動作の記録（ログ）を残し、止まったときに気づける体制を作る。
Webhookの注意点
- 受け取るURLは、インターネットから届く必要があるため、第三者からも送られる可能性があります。提供元が定める検証の方法（共有の秘密情報による署名の確認など）を、公式ドキュメントで確認し、必ず実施してください。
- 秘密情報（検証用の鍵）は、パスワードと同じ扱いで管理します。
- 同じ通知が、再送などで複数回届くことがあります。同じ処理を2回実行しても問題ない設計（冪等性）が重要です。
- 受信側が止まっていると、通知を取りこぼす場合があります。再送の仕組みの有無と期間は、サービスごとに異なるため、公式で確認します。
- 通知に含まれる個人情報の扱いに注意します。
Webhookでよくあるミス
- 検証をせず、誰から来た通知でも処理してしまう。
- 同じ通知が2回届いて、二重に登録や課金の処理が走る。
- 受信側の処理が重く、応答が遅れて、通知が失敗扱いになる。
- 受信URLを公開のまま、動作の記録を残さない。
Webhookのチェックリスト
- 必要なイベントを、公式のドキュメントで確認したか。
- 通知の送り主を検証する仕組みを入れたか。
- 二重の通知に備えた設計か。
- 失敗や遅延に気づく記録と通知があるか。
- 秘密情報の保管場所を決めたか。
WebhookのFAQ（よくある質問）
Q. Webhook と API は、どちらを使うべきですか。
A. 変化をすぐに知りたいならWebhook、必要なときに自分から取りに行きたいならAPIが向きます。併用も一般的で、通知を受けて、詳細をAPIで取りに行く設計もあります。
Q. プログラミングができなくても使えますか。
A. 連携用のサービスを使えば、コードなしで受け取り側を作れる場合があります。仕組みと注意点の理解は必要です。
Q. Webhook の通知は、必ず届きますか。
A. 通信の失敗などで、届かない場合があります。再送の有無は、サービスごとに異なるため、公式のドキュメントで確認し、取りこぼしに備えます。
筆者の見解（Webhook）
Webhook は便利ですが、誰でも叩けるURLを自分で公開することになる点が、最大の落とし穴だと考えます。連携が動いた喜びで、送り主の検証を後回しにしがちですが、そこが、なりすましの入口になるためです。私見では、最初のテストの段階から検証の仕組みを入れ、二重の通知にも耐える設計にしておくことが、自動化を長く安全に使うための条件だと思います。
Webhookの関連項目
出典（一次情報）
本記事は一般的な情報の提供を目的としています。SaaS・ツールの機能・料金・無料枠・仕様は頻繁に更新されるため、最新の内容は各社の公式ページでご確認ください。契約・法務・セキュリティに関する判断は、専門家や社内の担当部門にご相談ください。「筆者の見解」は一つの考え方です。