--- title: "Webhooks" description: "KOMOJUのWebhookを使ったイベント通知の仕組みを説明します — Webhookの作成、デリバリー、シークレットトークンによる署名検証、リトライの動作について解説します。" url: "https://docs.komoju.com/ja/docs/introduction/webhooks" source_url: "https://docs.komoju.com/ja/docs/introduction/webhooks.md" language: ja last_modified: "2026-03-31" --- Webhook を使うと、 KOMOJU で発生したイベントの通知を受けることができます。イベントが発生すると、イベントの情報が記載された JSON オブジェクトが含まれた POST リクエストを、お使いのアプリケーションに送信します。Webhook を使うことで、お使いのアプリケーションが支払の保存・返金時など重要なイベントをすぐに受け取れるようになり、これらのイベントをアプリケーション内で処理することが可能になります。 # Webhookの作成 ## 標準ケース（ほとんどのマーチャント向け） 新しい Webhook は、KOMOJU ダッシュボードの Webhook 作成ページ（各種情報 → Webhook）から作成できます。 Webhook を作成する前に、Webhook を受信するための エンドポイント URL をアプリケーション側で設定する必要があります。エンドポイント URL の設定が完了したら、新しい Webhook を作成できます。 Webhook 作成後、イベントの受信処理をテストできるよう、即座に ping イベント が送信されます。 ## 高度なケース 上記の方法で大半のユースケースには十分ですが、Payments API を利用しているマーチャントは、支払いごとに Webhook を定義することも可能です。これにより、支払い単位で Webhook の URL を細かく制御できます。 ただし、この方法は実装の複雑性が大きく増すため、本当に必要な場合を除き推奨していません。原則として、上記のような 集中管理型の Webhook を利用することをおすすめします。 支払いごとの Webhook は、API リクエスト内の webhooks パラメータを使用して設定できます。 この支払い単位の Webhook は、集中管理型の Webhook と 並行して動作 し、両方の Webhook にイベントが送信されます。 ```curl curl --location 'https://komoju.com/api/v1/payments' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "amount": 1000, "currency": "JPY", "tax": 100, "payment_details": { "type": "credit_card", "month": "08", "number": "4111111111111111", "year": "2028" }, "webhooks": [ { "url": "https://webhook.site/c41f4494-72e4-4402-9377-7a05fc61c88d", "secret_key": "test", "events": [ "payment.captured", "payment.authorized", "payment.updated" ] } ] }' ``` 支払い単位の Webhook で利用可能なイベントは以下のとおりです。 ``` "payment.authorized", "payment.captured", "payment.updated", "payment.expired", "payment.cancelled", "payment.refund.created", "payment.refunded", "payment.failed", "payment.marked.as.fraud" ``` # イベント 特定の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リクエスト例 ```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": "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" } ``` ```http 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 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