Webhook

Webhook を使って KOMOJU で発生したイベントの通知を受けることができます。イベントが発生すると、イベントの情報が記載された JSON オブジェクトが含まれた POST リクエストを、お使いのアプリケーションに送信します。Webhook を使うと、お使いのアプリケーションが、支払の保存・返金時など重要なイベントが発生したときにすぐにわかるようになりますので、このようなイベントをアプリケーション内で処理することが可能になります。

Webhook の作成ページから新しい Webhook を作成することができます。Webhook を作成する前に、アプリケーションが Webhook を受信できるように、エンドポイント URL をセットアップしましょう。エンドポイント URL のセットアップが完了したら、新しい Webhook が作成できます。Webhook 作成後、すぐに ping イベントを送信いたしますので、イベントの確認が簡単に行えます。

イベント

特定の API リソース上でアクションが発生すると、KOMOJU 内でイベントが発生します。アプリケーションが決済の完了や返金などペイメントのステータス変更のような重要なイベントの通知設定をしているかどうかご確認ください。Webhook を作成するときには、通知したいイベントを選択する必要があります。

通知可能なイベント

イベント	詳細
`ping`	ping イベント
`customer.created`	カスタマーの作成
`customer.updated`	カスタマーの更新
`customer.deleted`	カスタマーの削除
`payment.authorized`	ペイメントの仮売上化
`payment.captured`	ペイメントの決済完了
`payment.updated`	ペイメントの更新完了
`payment.expired`	ペイメントの有効期限切れ
`payment.cancelled`	ペイメントのキャンセル
`payment.refund.created`	ペイメントの返金の作成
`payment.refunded`	ペイメントの返金
`payment.failed`	ペイメントの処理失敗
`subscription.created`	定期課金の作成
`subscription.captured`	定期課金の決済完了
`subscription.failed`	定期課金の処理失敗
`subscription.suspended`	定期課金の一時停止
`subscription.deleted`	定期課金の削除
`settlement.created`	出金の作成

Webhook デリバリー

Webhook デリバリーは、発生したイベントの情報を含んだ Webhook URL への POST リクエストのことです。各 Webhook デリバリーには、メタデータのヘッダとイベントに関する JSON オブジェクトが含まれます。

HTTP ヘッダー

名称	詳細
`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`

属性

名称	詳細
`type`	Webhook イベントのタイプ (例: `payment.captured`)
`object`	`event`
`data`	API リソースを表したハッシュ
`created_at`	これは次のような ISO 8601 フォーマットのタイムスタンプで表します：YYYY-MM-DDTHH:MM:SSZ.

Webhook デリバリーのサンプル

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": "test@example.com",
      "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"
}

ping イベント

Webhook が作成されると、すぐにアプリケーションの Webhook URL に ping イベントを送信します。このイベントには、作成された Webhook の設定情報が含まれます。テストしたいときには、Webhook ページにある "再送信" ボタンをクリックして Webhook デリバリーを再送信することができます。

Webhook デリバリーのサンプル

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)

注意:署名を確認するときに、== のような単純な文字列比較は、タイミングアタックの被害に遭い易いので推奨いたしません。代わりに、定数時間アルゴリズムを推奨しております。もしも ruby を使用しているなら、secure_compare を使うと上手く行きます。

require "sinatra"

WEBHOOK_SECRET_TOKEN = "keep it secret, keep it safe!"

post '/hook' do
  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 アドレスは避けられない要因により 予告なしに変更 する可能性があります。

54.92.34.91
54.250.139.124
54.64.21.55
54.250.170.194
52.193.228.45
52.192.41.65