先に要点
Webhook という言葉はよく見かけるのに、初心者のうちは API と何が違うのか分かりにくい と感じやすいと思います。
実際、どちらも「サービス同士をつなぐもの」と説明されがちなので、最初は混ざりやすいです。
この記事では、2026年4月4日時点で Stripe Docs の Webhooks と Resolve webhook signature verification errors、GitHub Docs の About webhooks、Slack の Incoming webhooks を確認しながら、Webhook とは何か、API との違い、実務でよくある使い方、受け側で気をつけたい 署名検証 と 冪等性 まで整理します。
Push や Pull Request をきっかけに自動化したい話とつなげて見たいなら、GitHub Actionsとは？できること・最初の使い方を初心者向けに解説 もあわせて読むと流れがつかみやすいです。
API の考え方そのものを整理したいなら、GraphQLとは？REST APIとの違いと向いている場面を初心者向けに解説 も続けて読むと比較しやすいです。
API仕様書をチームで共有するところまで整理したい場合は、OpenAPI / Swaggerとは？API仕様書をチームで共有する基本を整理 もあわせて読むと実務につなげやすいです。
Webhookの再送や集中アクセスをどう受け止めるかまで見るなら、APIのレート制限とは？ログイン・Webhook・外部APIで必要になる理由 も続けて読むと設計しやすいです。
Webhookとは何か
Webhook は、イベントが起きたときに、相手のサービスがあらかじめ決めた URL へ HTTP リクエストを送って知らせてくれる仕組みです。
ざっくり言うと、何かあったら呼ぶので、この URL で待っていてください という形です。
たとえば、
- 決済が完了した
- GitHub で push された
- フォーム送信があった
- チャットへ通知したい
のようなイベントが起きたときに、相手側からこちらのサーバーへ通知が届きます。
初心者向けには、相手がベルを鳴らしてくれる仕組み と考えると入りやすいです。こちらから何度も見に行かなくても、必要なタイミングで知らせてもらえるのが便利なところです。
APIとの違いは何か
ここが一番混ざりやすいポイントです。
| 観点 | API | Webhook |
|---|---|---|
| 基本の向き | こちらから相手へ取りに行く | 相手からこちらへ知らせてもらう |
| 典型例 | 顧客情報を取得する、在庫を更新する | 支払い完了通知、push 通知、フォーム通知 |
| タイミング | 必要になったときに呼ぶ | イベントが起きたときに飛んでくる |
| 実装側の発想 | 取りに行く処理を書く | 受ける URL と検証処理を書く |
要するに、API は 問い合わせ、Webhook は 通知 と考えるとかなり整理しやすいです。
もちろん実務ではどちらか片方だけではなく、両方を組み合わせることもかなり多いです。
次の図では、API（Pull型）と Webhook（Push型）それぞれの通信の流れをステップで比較できます。
実務でよくある使い方
実務でよく見る使い方は、このあたりです。
決済完了を受ける
Stripe のような決済サービスで、支払い成功や失敗を Webhook で受けて、注文状態やメール送信を更新します。
GitHub のイベントを受ける
フォーム送信や外部サービス連携
フォーム入力後に Slack や社内システムへ通知したり、別の業務フローを起動したりします。
状態変化を他システムへ伝える
会員登録、在庫更新、配送完了などをきっかけに、別システムへ連携を流すときにも使われます。
ここでの共通点は、何か起きた瞬間に次の処理を動かしたい ということです。定期的に API を叩いて見に行くより、イベントで受けた方が素直なケースがかなりあります。
どういう流れで動くのか
Webhook の流れはかなりシンプルです。
- 1
通知先URLを登録する
相手サービスに、こちらの通知先URLを登録しておく。
- 2
イベントが起きる
決済完了や push など、相手サービス側でイベントが起きる。
- 3
HTTP リクエストが届く
相手サービスが、登録された URL へ HTTP リクエストを送る。
- 4
受け取って処理する
こちらのサーバーが受け取って処理する。
- 5
200 系を返す
正常なら 200 系を返す。
文章だけだと難しく見えますが、構造としては イベント通知用の API エンドポイントを受け側に1本作る くらいのイメージです。
ただし、実務ではここに 署名検証 や 冪等性 が入ってきます。
よくある誤解
Webhookは「ただの POST を受ければよい」ではない
ここはかなり大事です。
初心者のうちは、URL を1本作って POST を受ければ終わり に見えやすいです。
でも実務では、次の点まで見ないと危ないです。
送り主
本当に正しい送り主なのか
再送
再送されても壊れないか
時間
重い処理でタイムアウトしないか
エラー時
エラー時に相手が再試行するか
APIの代わりになるわけではない
Webhook は便利ですが、欲しい情報を何でも通知してくれるわけではありません。
通知でイベントを受けて、そのあと詳しい情報は API で取りに行く、という組み合わせはかなり普通です。
署名検証はなぜ必要か
署名検証 は、届いた通知が本当にそのサービスから送られたものかを確かめるための処理です。
Stripe も GitHub も、Webhook では署名やシークレットを使って確認する考え方を案内しています。
ここを雑にすると、第三者が勝手に同じ形式のリクエストを送って、支払い完了扱い や 社内処理の起動 を起こせる可能性があります。初心者向けには、通知を受けたらまず送り主確認をする と覚えるとかなり安全です。
冪等性はなぜ必要か
冪等性 は、同じ通知が複数回来ても結果が壊れないようにする考え方です。
Webhook では、タイムアウトやエラー時に相手側が再送することがあります。
このため、次のような事故を防ぐ必要があります。
注文
同じ注文を二重に確定する
メール
同じメールを何度も送る
在庫
同じ在庫更新を何度も流す
実務では、イベント ID を保存して二重処理を避けたり、この注文はすでに反映済み を確認してから更新したりします。
実務での作り方をざっくり言うと
実務では、だいたい次の流れにするとかなり安定します。
Webhook の受け口の作り方
- 1専用の受信 URL を作る
Webhook を受けるための専用の URL を用意する。
- 2
- 3イベント種別を確認する
どのイベントの通知なのかを確認する。
- 4まず短く 200 を返す
まず短く 200 を返せる構造にする。
- 5重い処理は非同期へ
重い処理はキューや非同期処理へ逃がす。
- 6
ここで大事なのは、受け口を軽くして、あとで安全に処理する ことです。その場で全部やろうとすると、タイムアウトや再送で壊れやすくなります。
どういう場面ならWebhookが向いているか
Webhook が向いているのは、次のような場面です。逆に、今この情報を取得したい なら API の方が自然です。
Webhook と API が向いている場面
つまり、通知には Webhook、参照や操作には API が向いています。
まとめ
Webhook は、イベントが起きたときに相手からこちらへ通知してもらう仕組みです。
API が 取りに行く のに対して、Webhook は 知らせてもらう 側に向いています。
実務では、決済、GitHub、フォーム、チャット通知、社内連携などでかなりよく使われます。
ただし、便利だからこそ、署名検証 と 冪等性 を入れずに雑に受けると事故になりやすいです。
最初は、通知を受ける仕組み 送り主確認 再送に強くする の3つを押さえるだけでもかなり見通しがよくなります。
そのうえで、必要なら通知後に API で詳細を取りに行く、という組み合わせで考えると整理しやすいです。
Webhook に関するよくある質問
Webhook と API、どちらを使うべき？
イベント駆動なら Webhook、リクエスト駆動なら API。受け取った瞬間に処理したい 通知系（決済、PR マージ、フォーム送信）は Webhook、今のデータが欲しい 取得系（残高照会、ユーザー検索）は API。組み合わせて使うことも多く、Webhook で通知を受けて API で詳細を取りに行く、というパターンが定番です。
署名検証は本当に必要？
必須です。Webhook 受信エンドポイントは公開 URL なので、誰でも偽の POST を投げられます。Stripe、GitHub、Slack などは署名（HMAC）を返してくれるので、必ず検証してから処理してください。検証なしで受けると、偽の決済成功イベント で残高を操作される、といった事故が起きます。
冪等性って何？なぜ必要？
同じリクエストを複数回受けても結果が変わらない 性質のことです。Webhook は再送されることがあり（送信側のリトライ、ネットワーク失敗）、同じイベントが2回届くと2回処理してしまうと困ります。イベント ID を保存して、既に処理済みなら skip する実装にします。
Webhook URL を本番デプロイ前にテストするには？
ngrok、Cloudflare Tunnel、webhook.site などのトンネリングサービスで、ローカル開発環境を一時的に公開 URL として晒せます。Stripe / GitHub なら開発用の sandbox や、CLI の stripe listen / gh api で local forward もできます。
Webhook が届かないときの切り分け方は？
(1) 送信側のダッシュボードで配信ログを確認（4xx / 5xx / タイムアウトのどれか）、(2) 受信側のアクセスログでリクエストが届いているか確認、(3) ファイアウォール / WAF / CDN がブロックしていないか、(4) 署名検証で弾いていないか、(5) タイムアウト（多くは 5〜10 秒）で切れていないか。
重い処理を Webhook で同期実行してもいい？
避けるべきです。Webhook は通常 5〜10 秒以内に 2xx を返さないと再送扱いされます。処理を受け取ったらキュー（SQS、Cloud Tasks、Redis Queue 等）に積んで即 2xx を返し、実処理は非同期ワーカーでやるのが定石。
Webhook と SSE / WebSocket の使い分けは？
Webhook は サーバー → サーバー の通知（クライアント間ではなく）、SSE / WebSocket は サーバー → ブラウザ のリアルタイム配信に使います。ブラウザに通知を届けたいなら SSE か WebSocket、別サーバー（自社や外部）に通知を届けたいなら Webhook です。
参考情報
- Stripe Docs: Webhooks
- Stripe Docs: Receive Stripe events in your webhook endpoint（署名の検証）
- GitHub Docs: About webhooks
- Slack API: Incoming webhooks