Webhook とは｜仕組みと API（ポーリング）との違い、使いどころ

Webhook とは、あるシステムで出来事が起きたときに、あらかじめ登録しておいた URL へ HTTP で知らせを送る仕組みです。 「支払いが完了した」「予約が入った」「書類が発行された」といった出来事を、相手のシステムに数秒で伝えられます。受け取る側は、知らせが届くのを待つだけで済み、何度も問い合わせる必要がありません。ここでは仕組みと、API を定期的に呼ぶ方法（ポーリング）との違い、使いどころを整理します。

Webhook の仕組み

1. 受け取る側が、知らせを受け取る URL を用意し、送る側の管理画面や API に登録します
2. 送る側で出来事が起きると、その URL に HTTP の POST で知らせ（本文は多くが JSON）を送ります
3. 受け取る側は、届いた知らせを確かめて、成功の応答（2xx の HTTP ステータス）を返します
4. 成功の応答が返らなかった場合、多くのサービスは間隔を空けて送り直します

届く本文の例です。出来事の種類、いつ起きたか、対象の ID が入っています。

{
  "type": "booking.created",
  "timestamp": "2026-11-07T09:00:00+09:00",
  "data": { "booking_id": "bk_0001", "customer_id": "cu_0001" }
}

ポーリングとの違い

Webhook を使わない場合、受け取る側が相手の API を数分おきに呼び、「新しいものがないか」を確かめます。これをポーリングと呼びます。

GitHub のドキュメントも、Webhook はポーリングより手間と資源が少なく済み、ポーリングは API の呼び出し回数の上限に早く達しやすいと説明しています。一方で、受け取る側がインターネットから届く URL を持てない場合（社内のネットワークの中だけのシステムなど）は、ポーリングのほうが組みやすいこともあります。

受け取る側がすること

• 署名を確かめる：URL は外から誰でも呼べるため、届いた知らせが本当に送り主から来たかを、本文に付いた署名で確かめます。署名の形式は送り主ごとに違いますが、共通の仕様として Standard Webhooks があります
• すぐに応答を返す：重い処理を終えてから応答すると、送り主が「失敗」とみなして送り直すことがあります。GitHub は、受け取ってから 10 秒以内に 2xx を返すよう求めています。受け取ったらキューに積んで応答し、処理は後で行います
• 重複に備える：送り直しで同じ知らせが 2 回届くことがあります。知らせごとの ID を記録し、処理済みのものは飛ばします
• 順番に頼らない：届く順番が出来事の順番と一致するとは限りません。時刻や版の番号で新旧を判断するか、知らせを受けたら API で最新の状態を取りに行きます

送る側が用意すること

自社のサービスから顧客のシステムに Webhook を送る場合は、送信先の登録の画面、署名と鍵の管理、送り直し、配信の記録、失敗が続く送信先の停止と通知が必要です。作業の範囲と、外部のサービスに任せる場合との比較は「Webhook の送信を外部サービスに任せるメリット」で詳しく扱っています。

使いどころと向かない場面

向いているのは、出来事が起きたらすぐに知りたいものです。

• 決済の完了・失敗、請求書の支払い
• 予約の作成・変更・取り消し
• 帳票の発行の完了、ファイルの変換の完了
• 外部サービスでの会員の登録・退会

向かないのは、大量のデータをまとめて移すもの（毎晩のファイルの受け渡しのほうが確実）、受け取る側がインターネットに URL を出せないもの、知らせが届かなかったときに業務が止まるのに、送り直しの期間を過ぎた分を拾う手段がないものです。最後の場合は、Webhook に加えて、定期的に API で突き合わせる仕組みを置きます。

Webhook Admin のご案内

当社の「Webhook Admin」は、Webhook の送信をまとめて引き受けるサービスです。Standard Webhooks 形式の署名付きで送信し、失敗した場合は自動で送り直します。送信先ごとの順番の保証、本文の書き換え、Amazon SQS・Google Cloud Pub/Sub などへの送信、受信側からのポーリング、障害の通知、顧客向けの設定画面、固定の送信元 IP アドレスに対応しています。料金は製品サイトに掲載しています。

出典

• GitHub Docs: About webhooks
• GitHub Docs: Best practices for using webhooks
• Stripe: Webhook エンドポイントで Stripe イベントを受信する
• Standard Webhooks