Webhooks
KOMOJUから通知を受ける仕組み
Webhook を使うと、 KOMOJU で発生したイベントの通知を受けることができます。イベントが発生すると、イベントの情報が記載された JSON オブジェクトが含まれた POST リクエストを、お使いのアプリケーションに送信します。Webhook を使うことで、お使いのアプリケーションが支払の保存・返金時など重要なイベントをすぐに受け取れるようになり、これらのイベントをアプリケーション内で処理することが可能になります。
新しい Webhook は Webhook の作成ページから作成できます。アプリケーションが Webhook を受信できるように、エンドポイント URL を事前にセットアップしておきましょう。エンドポイント URL のセットアップが完了したら、新しい Webhook が作成できます。疎通確認のため、Webhook が作成されるとすぐに KOMOJU から ping イベントが送信されます。
イベント
特定のAPIリソース上でアクションが発生すると、KOMOJU 内でイベントが発生します。アプリケーションが決済の完了や返金などペイメントのステータス変更のような重要なイベントの通知設定をしているかどうかご確認ください。Webhook を作成する際は、通知したいイベントを選択する必要があります。
Event | Description |
---|---|
ping | Webhookをテストする為のpingイベント |
payment.authorized | ペイメントの仮売上化 |
payment.captured | ペイメントの決済完了 |
payment.updated | ペイメントの更新 |
payment.expired | ペイメントの有効期限切れ |
payment.cancelled | ペイメントのキャンセル |
payment.refund.created | ペイメントの返金の作成 |
payment.refunded | ペイメントの返金 |
payment.failed | ペイメントの試みが失敗しました (再試行が可能です) |
customer.created | カスタマーの作成 |
customer.updated | カスタマーの更新 |
customer.deleted | カスタマーの削除 |
subscription.created | 定期課金の作成 |
subscription.captured | 定期課金の決済完了 |
subscription.failed | 定期課金の処理失敗 |
subscription.suspended | 定期課金の一時停止 |
subscription.deleted | 定期課金の削除 |
settlement.created | 出金の作成 |
Webhook デリバリー
Webhook デリバリーは、発生したイベントの情報を含んだ Webhook URL への POST リクエストのことです。各 Webhook デリバリーには、メタデータのヘッダとイベントに関する JSON オブジェクトが含まれます。
HTTP ヘッダー
Header | Description |
---|---|
X-Komoju-ID | Webhook デリバリーのユニーク ID |
X-Komoju-Signature | セキュリティトークンと Webhook のリクエストボディを使って計算された SHA-2 HMAC |
X-Komoju-Event | Webhook イベントの名称 (例: payment.captured) |
User-Agent | Komoju-Webhook |
Content-Type | application/json |
Webhook のリクエスト body
KOMOJU からの Webhook のリクエスト body には以下の属性で構成されています。
Attribute | Description |
---|---|
type | Webhook イベントのタイプ (例: payment.captured) |
object | "event" |
data | イベントごとに異なるポリモーフィックなオブジェクト |
created_at | イベント発生時刻 ISO 8601形式: YYYY-MM-DDTHH:MM:SSZ |
HTTPリクエスト例
POST http://example.com/hook HTTP/1.1
Host: example.com
X-Komoju-Id: 6cul2yma626autvvxz2xre1qr
X-Komoju-Signature: 75e653443e6543ee4c4b0665c73a4818216c9464f4a3ac959bff5ebafc105693
X-Komoju-Event: payment.authorized
User-Agent: Komoju-Webhook
Content-Type: application/json
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
{
"id": "dv7ywuavew3n2meqsllj5bbob",
"type": "payment.authorized",
"resource": "event",
"data": {
"id": "8xz5cn01gkt37cz0myd98k2f1",
"resource": "payment",
"status": "authorized",
"amount": 1000,
"tax": 80,
"customer": null,
"payment_deadline": "2018-11-20T14:59:59Z",
"payment_details": {
"type": "bank_transfer",
"email": "[email protected]",
"order_id": "Y5236584956",
"bank_name": "三井住友銀行",
"account_branch_name": "ひなぎく",
"account_number": "6",
"account_type": "普通預金",
"account_name": "株式会社DEGICA(カブシキガイシャ デジカ)",
"instructions_url": "https://komoju.com/ja/instructions/8xz5cn01gkt37cz0myd98k2f1"
},
"payment_method_fee": 0,
"total": 1080,
"currency": "JPY",
"description": null,
"captured_at": null,
"external_order_num": "123",
"metadata": {
},
"created_at": "2018-11-13T06:19:49Z",
"amount_refunded": 0,
"locale": "ja",
"refunds": [
],
"refund_requests": [
]
},
"created_at": "2018-11-13T06:19:49Z"
}
POST http://example.com/hook HTTP/1.1
Host: example.com
X-Komoju-Id: 1lqjmj6k7li996cdiqxqqzf1k
X-Komoju-Signature: ee52defb62c1d48125741bfe92a13b6cbffc97b0b3a26b5cab582f766a4ae97e
X-Komoju-Event: ping
User-Agent: Komoju-Webhook
Content-Type: application/json
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
{
"id": "do33foclbroj52ib9whb6yh4m",
"type": "ping",
"resource": "event",
"data": {
"id": "bll40gxhuhcw19vor5kx55akw",
"resource": "webhook",
"url": "http://example.com/hook",
"active": true,
"event_list": [
"ping",
"payment.captured"
],
"created_at": "2018-11-13T06:19:49Z"
},
"created_at": "2018-11-13T06:19:49Z"
}
シークレットトークン
Webhook リクエストが KOMOJU から送信されるものであることを証明するために、KOMOJU上でWebhook を作成・更新したときに設定するシークレットトークンを使用して、SHA-2 HMAC 署名を計算します。
シークレットトークンがセットされると、リクエストには HMAC カスタマーヘッダーである X-Komoju-Signature が含まれます。このヘッダーはシークレットトークンをキーとして計算したリクエストボディの HMAC のことです。シークレットトークンを使うことで、その署名を計算して、KOMOJU から送信された署名と比較できます。
Rubyで署名を確認する例
require "sinatra"
WEBHOOK_SECRET_TOKEN = "keep it secret, keep it safe!"
post '/hook' do
# NOTE: it's important to use the raw, unmodified request body here.
# If you parse the body JSON and then re-encode, you might be unable to verify.
request_body = request.body.read
signature = OpenSSL::HMAC.hexdigest('sha256', WEBHOOK_SECRET_TOKEN, request_body)
return 400 unless Rack::Utils.secure_compare(signature, request.env["HTTP_X_KOMOJU_SIGNATURE"])
"Hello World"
end
再送信
サーバーの反応が正常なステータスコードでない場合や、KOMOJU がサーバーと正常に通信できない場合は、Webhook の送信を最大 25 回リトライします。リトライの間隔は徐々に長くなり、最後は 100 時間ほどの間隔が開いてリトライが実行されます。最後のリトライは最初の送信が実行されてから 25 日後に発生し、その後デリバリーは失敗としてマークされます。
もしも、サーバーが正常なステータスコードを返したにもかかわらずそのイベントを処理しなかった場合、ペイメントのダッシュボードからいつでも Webhook デリバリーを再送信できます。
IPアドレス
以下に弊社の Webhook 送信サーバーの IP アドレスを提供いたしますが、IP ベースのアクセスコントロールの使用は推奨いたしません。代わりに、シークレットトークンのセクションに記載されている方法をチェックして Webhook の信頼性を確認してください。
なお、次の IP アドレスは避けられない要因により予告なしに変更する可能性があります。
- 52.193.228.45
- 52.192.41.65
- 54.249.171.29
- 35.74.48.209
- 52.193.206.171
- 52.194.203.5
- 54.179.35.81
- 52.74.4.250
- 13.250.133.195
Updated about 1 month ago