Webhook

概要

Webhook（ウェブフック）とは、「あるイベントが発生したときに、自動的にHTTPリクエストを送信する仕組み」です。

例えば、GitHubにコードをpushしたら自動的にビルドサーバーに通知が送られたり、 ECサイトで注文が入ったら在庫管理システムに自動で連絡が行ったりします。 これがWebhookの仕組みです。

WebhookはAPIと組み合わせて使われることが多く、JSON形式でデータをやり取りします。HTTP POSTリクエストで自動通知を実現する、 現代のWeb開発に欠かせない技術です。

想像してみてください。あなたが宅配便を注文したとき、配達員が「荷物が到着しました」と いちいち確認の電話をかけてくるのではなく、自動的にSMSで通知が来ますよね。 Webhookは、まさにこの「自動通知」をプログラム間で実現する技術です。

WebhookとAPIの違い

WebhookとAPIは似ているようで、動作の仕組みが異なります：

💡 イメージ：APIは「電話をかけて聞く」、Webhookは「着信があったら自動で通知が来る」という感じです。

Webhookの仕組み

Webhookは以下のような流れで動作します：

1. イベント登録：事前に「こういうイベントが起きたら、このURLに通知してください」と設定する
2. イベント発生：実際にそのイベントが発生する（例：GitHubへのpush、決済完了など）
3. HTTP POSTリクエスト送信：登録されたURLに、イベントの詳細情報をJSONなどの形式で自動送信
4. 受信側の処理：Webhookを受け取ったサーバーが、必要な処理を実行する

Webhookの使用例

GitHubとCI/CD

GitHubにコードをpushすると、自動的にビルドサーバー（GitHub Actions、CircleCIなど）に通知が送られ、 テストやデプロイが自動実行されます。

Stripe（決済サービス）

決済が完了したら、あなたのサーバーに自動で通知が送られます。 それを受け取って、商品のダウンロードリンクをメール送信したり、会員登録を完了させたりします。

Slack通知

お問い合わせフォームが送信されたら、Slackのチャンネルに自動で通知を送ることができます。

Trello / Notion

カードが追加されたり、ステータスが変更されたりしたら、 他のツールやシステムに自動で情報を連携できます。

Webhookのペイロード

Webhookで送信されるデータをペイロード（Payload）と呼びます。 通常はJSON形式で送られます。

{
  "event": "order.created",
  "timestamp": "2026-01-06T10:30:00Z",
  "data": {
    "order_id": "12345",
    "customer": {
      "name": "山田太郎",
      "email": "yamada@example.com"
    },
    "items": [
      { "product": "商品A", "quantity": 2, "price": 2500 }
    ],
    "total": 5000
  }
}

受信側のサーバーは、このJSONデータを解析して、必要な処理を実行します。

Webhookのセキュリティ

Webhookは外部からHTTPリクエストを受け取るため、セキュリティ対策が重要です：

1. 署名検証（Signature Verification）

多くのサービスは、Webhookに「署名」を付けて送信します。 受信側はこの署名を検証することで、本当にそのサービスから送られてきたか確認できます。

2. HTTPS必須

WebhookのエンドポイントURLは必ずHTTPSにしましょう。 通信が暗号化されるため、中間者攻撃を防げます。

3. IPアドレス制限

可能であれば、特定のIPアドレスからのリクエストのみを受け付けるように設定します。

4. リトライ処理

受信側のサーバーがダウンしていた場合、多くのサービスは自動的に再送信してくれます。 冪等性（何度実行しても結果が同じ）を保つ設計が大切です。

Webhookの設定方法（GitHub例）

GitHubでWebhookを設定する手順：

1. GitHubリポジトリの「Settings」→「Webhooks」→「Add webhook」
2. Payload URL: Webhookを受け取るURLを入力（例：https://your-server.com/webhook）
3. Content type: application/jsonを選択
4. イベント選択: どのイベントで通知するか選択（push、pull requestなど）
5. 「Add webhook」をクリックして完了

これで、選択したイベントが発生するたびに、指定したURLに自動でPOSTリクエストが送信されます。