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 ペイメントの処理失敗
payout.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 から送信されるものであることを証明するために、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