先に要点
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とは？できること・最初の使い方を初心者向けに解説 もあわせて読むと流れがつかみやすいです。
Webhookとは何か
Webhook は、イベントが起きたときに、相手のサービスがあらかじめ決めた URL へ HTTP リクエストを送って知らせてくれる仕組みです。
ざっくり言うと、何かあったら呼ぶので、この URL で待っていてください という形です。
たとえば、
- 決済が完了した
- GitHub で push された
- フォーム送信があった
- チャットへ通知したい
のようなイベントが起きたときに、相手側からこちらのサーバーへ通知が届きます。
初心者向けには、相手がベルを鳴らしてくれる仕組み と考えると入りやすいです。
こちらから何度も見に行かなくても、必要なタイミングで知らせてもらえるのが便利なところです。
APIとの違いは何か
ここが一番混ざりやすいポイントです。
| 観点 | API | Webhook |
|---|---|---|
| 基本の向き | こちらから相手へ取りに行く | 相手からこちらへ知らせてもらう |
| 典型例 | 顧客情報を取得する、在庫を更新する | 支払い完了通知、push 通知、フォーム通知 |
| タイミング | 必要になったときに呼ぶ | イベントが起きたときに飛んでくる |
| 実装側の発想 | 取りに行く処理を書く | 受ける URL と検証処理を書く |
要するに、API は 問い合わせ、Webhook は 通知 と考えるとかなり整理しやすいです。
もちろん実務ではどちらか片方だけではなく、両方を組み合わせることもかなり多いです。
実務でよくある使い方
実務でよく見る使い方は、このあたりです。
決済完了を受ける
Stripe のような決済サービスで、支払い成功や失敗を Webhook で受けて、注文状態やメール送信を更新します。
GitHub のイベントを受ける
push、Pull Request、release を受けて、CI、通知、デプロイのきっかけにします。
フォーム送信や外部サービス連携
フォーム入力後に Slack や社内システムへ通知したり、別の業務フローを起動したりします。
状態変化を他システムへ伝える
会員登録、在庫更新、配送完了などをきっかけに、別システムへ連携を流すときにも使われます。
ここでの共通点は、何か起きた瞬間に次の処理を動かしたい ということです。
定期的に API を叩いて見に行くより、イベントで受けた方が素直なケースがかなりあります。
どういう流れで動くのか
Webhook の流れはかなりシンプルです。
- 相手サービスに
通知先URLを登録する - イベントが起きる
- 相手サービスがその URL へ HTTP リクエストを送る
- こちらのサーバーが受け取って処理する
- 正常なら 200 系を返す
文章だけだと難しく見えますが、構造としては イベント通知用の API エンドポイントを受け側に1本作る くらいのイメージです。
ただし、実務ではここに 署名検証 や 冪等性 が入ってきます。
よくある誤解
Webhookは「ただの POST を受ければよい」ではない
ここはかなり大事です。
初心者のうちは、URL を1本作って POST を受ければ終わり に見えやすいです。
でも実務では、
- 本当に正しい送り主なのか
- 再送されても壊れないか
- 重い処理でタイムアウトしないか
- エラー時に相手が再試行するか
まで見ないと危ないです。
APIの代わりになるわけではない
Webhook は便利ですが、欲しい情報を何でも通知してくれるわけではありません。
通知でイベントを受けて、そのあと詳しい情報は API で取りに行く、という組み合わせはかなり普通です。
たとえば 支払いが完了した という通知だけ受けて、注文や顧客の詳細は別途 API で取りに行く、という構成はよくあります。
署名検証はなぜ必要か
署名検証 は、届いた通知が本当にそのサービスから送られたものかを確かめるための処理です。
Stripe も GitHub も、Webhook では署名やシークレットを使って確認する考え方を案内しています。
ここを雑にすると、第三者が勝手に同じ形式のリクエストを送って、支払い完了扱い や 社内処理の起動 を起こせる可能性があります。
初心者向けには、通知を受けたらまず送り主確認をする と覚えるとかなり安全です。
冪等性はなぜ必要か
冪等性 は、同じ通知が複数回来ても結果が壊れないようにする考え方です。
Webhook では、タイムアウトやエラー時に相手側が再送することがあります。
このため、
- 同じ注文を二重に確定する
- 同じメールを何度も送る
- 同じ在庫更新を何度も流す
のような事故を防ぐ必要があります。
実務では、イベント ID を保存して二重処理を避けたり、この注文はすでに反映済み を確認してから更新したりします。
実務での作り方をざっくり言うと
実務では、だいたい次の流れにするとかなり安定します。
- 専用の受信 URL を作る
- リクエストを受けたら 署名検証 をする
- イベント種別を確認する
- まず短く 200 を返せる構造にする
- 重い処理はキューや非同期処理へ逃がす
- イベント ID などで 冪等性 を担保する
ここで大事なのは、受け口を軽くして、あとで安全に処理する ことです。
その場で全部やろうとすると、タイムアウトや再送で壊れやすくなります。
どういう場面ならWebhookが向いているか
Webhook が向いているのは、次のような場面です。
- イベントが起きたらすぐ反応したい
- 定期ポーリングで何度も API を叩きたくない
- 外部サービスの状態変化を受けて処理を動かしたい
- 社内システム同士をイベント起点でゆるくつなぎたい
逆に、今この情報を取得したい なら API の方が自然です。
つまり、通知には Webhook、参照や操作には API が向いています。
まとめ
Webhook は、イベントが起きたときに相手からこちらへ通知してもらう仕組みです。
API が 取りに行く のに対して、Webhook は 知らせてもらう 側に向いています。
実務では、決済、GitHub、フォーム、チャット通知、社内連携などでかなりよく使われます。
ただし、便利だからこそ、署名検証 と 冪等性 を入れずに雑に受けると事故りやすいです。
最初は、通知を受ける仕組み 送り主確認 再送に強くする の3つを押さえるだけでもかなり見通しがよくなります。
そのうえで、必要なら通知後に API で詳細を取りに行く、という組み合わせで考えると整理しやすいです。
参考情報
- Stripe Docs: Webhooks
- Stripe Docs: Resolve webhook signature verification errors
- GitHub Docs: About webhooks
- Slack API: Incoming webhooks