Webhooks

KOMOJUから通知を受ける仕組み

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

新しい Webhook は Webhook の作成ページから作成できます。アプリケーションが Webhook を受信できるように、エンドポイント URL を事前にセットアップしておきましょう。エンドポイント URL のセットアップが完了したら、新しい Webhook が作成できます。疎通確認のため、Webhook が作成されるとすぐに KOMOJU から ping イベントが送信されます。

イベント

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

EventDescription
pingWebhookをテストする為の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 ヘッダー

HeaderDescription
X-Komoju-IDWebhook デリバリーのユニーク ID
X-Komoju-Signatureセキュリティトークンと Webhook のリクエストボディを使って計算された SHA-2 HMAC
X-Komoju-EventWebhook イベントの名称 (例: payment.captured)
User-AgentKomoju-Webhook
Content-Typeapplication/json

Webhook のリクエスト body

KOMOJU からの Webhook のリクエスト body には以下の属性で構成されています。

AttributeDescription
typeWebhook イベントのタイプ (例: 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 アドレスは避けられない要因により予告なしに変更する可能性があります。

  • 54.92.34.91
  • 54.250.139.124
  • 54.64.21.55
  • 54.250.170.194
  • 52.193.228.45
  • 52.192.41.65