Webhook

イベントオブジェクトが作成されるタイミングに指定されたURLへHTTP(S)リクエストを行う Webhook を利用できます。

Webhookを送る先のURLは設定画面から追加できます。 設定画面の下部のWebhookの欄にある、「新しいURLを追加」から、 URLと対象となる環境(テスト/商用)を指定して保存することで、次に発生するイベントからWebhookの送信が行われます。 Webhookの内容はPOSTリクエストで、リクエストボディが

{
  "created": 1375166634,
  "data": {
    "object": { "ping": true }
  },
  "id": "evt_gtbblu1sT4832q3",
  "livemode": false,
  "object": "event",
  "pending_webhooks": 0,
  "type": "ping"
}

というようなイベントオブジェクトのJSONです。 なお、Webhookのリクエストに対するレスポンスとして 200のステータスコードが返されるまで最大で5回、1時間おきにリクエスト を行います。

Webhookを受け取る実装例

Sinatra を用いてWebhookを受け取る実装の例を紹介します。 以下の例は 顧客オブジェクト が作成された際に作成される、typeプロパティが customer.created であるイベントをハンドリングしています。

require "sinatra"
require "json"

# 発信元を証明する文字列
CREDENTIAL = "6jsesEcHCdY2eLW6Bs3Mr82xeFWfVn67lcdd"

post "/webhook" do
  # ヘッダが期待しない値だったら終了
  return 400 if env["HTTP_X_WEBPAY_ORIGIN_CREDENTIAL"] != CREDENTIAL
  event = JSON.parse(request.body.read)
  if event["type"] == "customer.created"
    # 顧客が作成された時に行いたい処理をここに入れる
  end
  200 # 正しく処理が終了したらステータスコードは200を返す
end

イベントの type プロパティの内容については APIドキュメントのイベントオブジェクトの欄 をご覧ください。

Webhookによるリクエストの詳細

WebPayが送信するリクエストを受信するサーバで適切にハンドリングするための情報を示します。 これらの情報は機能拡張などに伴って変更することがあります。 定期的に確認し、実装を追随させるようにしてください。

リクエストヘッダ

WebPayからのリクエストは、次のヘッダを持つことを保証しています。

フィールド名 値の内容
Content-Type application/json
Content-Length リクエストボディのバイト長です。
User-Agent WebPay
X-Webpay-Origin-Credential Webhookの登録時に自動的に設定される発信元証明のための文字列です。 Webhookの登録後に個別ページで確認できます。 この値が表示されていない場合、個別ページの「発信元証明を再生成する」ボタンで設定できます。 各Webhookごとに固有の秘密の値で、WebPayからのリクエストであることを検証するために利用できます。

リクエストボディ

新たに発生したイベントオブジェクトです。APIレスポンスと同一のJSON形式です。 詳細は APIドキュメントのイベントオブジェクトの欄 をご覧ください。

送信元IPアドレス

WebPayからWebhookに登録されたURLにリクエストを行う際には、次のIPアドレスのいずれかが利用されます。 このIPアドレスのリストはやむをえない事情により予告なく変更することがあります。 送信元のアドレスが変更された後、このリストの更新が遅れる場合があることをご了承ください。 送信元の確認には、IPアドレスではなく X-Webpay-Origin-Credential ヘッダをご利用ください。

  • 54.199.160.221
  • 54.199.161.114
  • 54.199.180.229
  • 54.199.199.24

Webhookのセキュリティ

Webhookのデータには、課金オブジェクトの詳細や顧客オブジェクトのメールアドレスなど決済情報、個人に関する情報が含まれます。 商用環境で利用する場合は受信するサーバをHTTPSで指定し、通信データを傍受される危険性を減らしてください。

Webhookを受信しているサーバへ、第三者がWebhookによく似た不適切なデータを送信することで、受信処理が誤動作する可能性を考慮してください。 クリティカルなデータに関してはWebhookの値を信用せず、API経由でデータを再度取得して確認するのが堅牢ですが、より容易で効果的な方法として、 X-Webpay-Origin-Credential ヘッダの利用を推奨します。 Webhookの設定画面に表示される値と、リクエストのヘッダに入れられている値が一致すれば、WebPayからのリクエストであると確認できます。

発信元証明の取扱いにはAPIキーなどと同様に細心の注意を払ってください。 暗号化されていないHTTP接続ではこのヘッダの値も第三者に読み取られる恐れがありますので、必ずHTTPS接続を利用してください。

発信元証明が外部に流出した場合は、設定画面から再生成できます。 更新された後のWebhook送信ではすべて新しい値が利用されます。 再生成にあたっては、Webhookの受信処理は停止し、新しい発信元証明を受信サーバに設定してから再開してください。