👌

Webhookについて

に公開
Webhook
tech

はじめに

こんかいは、Webhook について掘り下げます。
stripeを導入する際、「Webhookで決済イベントを受け取る」と言う概念に突き当たりました。
この際、Webhookについて詳しく知ろうと思い、この記事を書きます。

そもそもWebhookとは

Webhookは、「イベントの“プッシュ通知”」です。
送信側が、何か起きた時にこちら側のURL（受信側）へHTTPリクエストを飛ばすことを言います。
例えば、決済成功、githubのPR作成時、google formの送信時、ビルド完了時、、と、あらゆるタイミングでWebhookが登場します。

Webhookの仕組み

  1. 送信側（Provider）：Stripe/GitHub等。イベント発生→POST送信
    送信内容
  • ペイロード：JSONなどでイベント内容
  • 署名：本物かどうか検証するためのHMAC等（共有シークレット）
  1. 受信側（Consumer）：こちら側のAPIエンドポイント（POST /webhook）
  • 2xxで速やかにACK（受領OK）を行う
  • 署名検証を必ず行う：ヘッダの署名をHMAC等で検証（改ざん/なりすまし対策）

※

  • Webhookは少なくとも1回以上届く想定（at-least-once）->重複に強い設計（冪等）にする。
  • 監査ログ：受信時刻・イベントID・署名検証結果・処理結果を記録することも大切

メリット

  • ポーリング不要（定期的に取りに行かなくていい）
  • リアルタイムに処理できる

ペイロードの例

POST /webhook HTTP/1.1
Content-Type: application/json
X-Provider-Signature: t=1730960000,v1=hex(hmac_sha256(secret, t + "." + body))

{
  "id": "evt_12345",
  "type": "payment.succeeded",
  "data": {
    "order_id": "ord_9ab1",
    "amount": 1200,
    "currency": "JPY"
  }
}

stripeの場合にWebhookを有効にするステップ

  1. エンドポイント（受信用URL）を用意する
  2. Webhook エンドポイントを登録する（Stripe ダッシュボード）
  3. 署名検証のための Secret を取得する
  4. サーバー側で Webhook ハンドラーを実装する（POST リクエストで受信できるように設定。）

(追記)stripe × Webhookで決済時にできること

単発決済の成功/失敗ハンドリング

payment_intent.succeeded / payment_intent.payment_failed で、成功時の配送開始や失敗時のリカバリ（別手段案内）などを実装することができる
（参考）
https://docs.stripe.com/payments/handling-payment-events

Discussion