メインコンテンツへスキップ

【EC-CUBE】Webhookの設定方法

更新

Webhookを設定すると、KOMOJUの決済イベントがEC-CUBEに通知され、注文ステータスが自動更新されます。

Webhookを設定しない場合、注文ステータスは自動更新されません。設定には、EC-CUBE側でのURL・シークレットの取得と、KOMOJU管理画面側での登録の両方が必要です。
また、WebhookはLiveモード・Testモードでそれぞれ個別に設定が必要です。片方のモードで登録しても、もう一方のモードには反映されません。

Webhookとは

Webhookを設定すると、KOMOJUで発生した決済イベント（売上確定・返金・キャンセルなど）がEC-CUBEに通知されます。設定しないと、注文ステータスは自動更新されません。

Webhook URLとシークレットをコピーする（EC-CUBE側）

  1. EC-CUBE管理画面で「KOMOJU決済 → 設定」を開きます
  2. 「Webhook設定」カードを開きます
  3. 「Webhookシークレット」（コピーボタンで値をコピー可能）と「WebhookエンドポイントURL」（KOMOJUからのイベント送信先URL）を確認し、それぞれコピーします

KOMOJU管理画面でWebhookを登録する

  1. KOMOJU管理画面にログインします
  2. 「管理 → Webhook」を開きます
  3. EC-CUBEでコピーしたエンドポイントURLとシークレットを入力し、Webhookを新規登録します
  4. 次のイベントをすべて有効にします
    • payment.captured
    • payment.refunded
    • payment.cancelled
    • payment.expired
    • payment.failed
    • payment.updated
    • payment.authorized

すべてのイベントの有効化が必要です

上記7つのイベントは、いずれもプラグインの動作に必要です。1つでも欠けると、注文ステータスが同期されないことがあります。登録時は、すべてのイベントにチェックが入っているか必ずご確認ください。

Liveモード・Testモードでの個別登録が必要な理由

KOMOJU管理画面のTestモードで登録したWebhookは、Liveモードには反映されません。同様に、Liveモードで登録したWebhookもTestモードには反映されません。

そのため、テスト環境での動作確認用と本番公開用で、それぞれのモードに切り替えたうえで個別にWebhookを登録してください。本番公開前は、KOMOJU管理画面をLiveモードに切り替えた状態で、上記の登録手順を再度行い、Liveモード用のWebhookが登録済みであることを確認してください。

Live／Testモードの切り替え方法

モードの切り替えは、KOMOJU管理画面左下のトグルスイッチで行います。

トグルスイッチが表示されない場合

このトグルスイッチはLiveモードが有効な場合にのみ表示されます。Liveモードの申請・審査が完了していない場合、トグルスイッチ自体が表示されないため、その場合は先にLiveモードの利用申請を完了してください。

Liveモードの利用には申請が必要です

Liveモード（商用環境）は申請・審査が必要です。KOMOJU管理画面右上の「決済を始める」ボタンから申請できます（審査および契約手続きが必要です）。Testモードは登録直後から利用でき、申請は不要です。詳細は「KOMOJUの機能を試す方法」をご確認ください。

関連記事