Webhook(ウェブフック)

このページで扱うトピック

Webhookを使用すると、加盟店のアカウントで特定のイベントが発生した際に、自動的にOpn Paymentsサーバーから指定されたHTTPSエンドポイントにリクエストが送られます。リクエストPOSTは、トリガーアクションに関するペイロードのデータを含むイベントオブジェクトで、加盟店が選択したURLに送信されます。重要なイベント(課金の完了など)が発生したときに、非同期で通知を受けることができます。

テスト環境と本番環境でURLを使い分けることもできます。テスト環境のエンドポイントは、https://dashboard.omise.co/test/webhooksから追加または変更が可能です。すべてのイベントデータは、ダッシュボード内の「イベント」で確認するか、Event APIから取得できます。

シリアライズ

POSTリクエスト(またはEvents APIを介して返される)のイベントオブジェクトは、トリガーイベントで送信されたOmise-Versionヘッダーの値に関係なく、イベントの時点でのデフォルトのAPI Versionに従って常にシリアライズされます。そのため、2017-11-02に設定されたアカウントに対して、curlを使用して -H "Omise-Version: 2019-05-29"を渡して作成された課金は、バージョン2019-05-29ではなく、Charge APIのバージョン2017-11-02に従ってシリアライズされたchargeオブジェクトが埋め込まれたイベント (charge.create) を生成します。その後、バージョン2019-05-29に更新した後も、この特定のイベントの埋め込みchargeオブジェクトはバージョン2017-11-02に従ってシリアライズされます。

要件とベストプラクティス

URLはHTTPSでなければならず、自己署名証明書ではなく、有効なSSL証明書を使用する必要があります。letsencrypt.orgでエンドポイント用の無料のSSL証明書を入手し、SSL testを使用して検証できます。

ステータスの更新が本物であることを確認するために、Webhook受信時のイベントを検証することをおすすめします。たとえば、charge.complete webhook イベントを受信した場合、Charge IDを使用してその特定の課金に対するGETリクエストを行い(例:/charges/chrg_test_no1t4tnemucod0e51mo)、statusを独自に検証します。

イベントのリスト

クレジットカードに関するイベント

Event Name Trigger
card.update カードが削除された時
card.destroy カードが更新された時

課金に関するイベント

Event Name Trigger
charge.capture. 課金が実売上化された時 (マニュアルキャプチャー設定の場合)
charge.complete. 課金が完了した時(注:3DS非対応カードの課金完了時には、このWebhookをトリガーしません)
charge.create 課金が作成された時
charge.expire 課金の有効期限が切れた時(Alipayのバーコード決済のみ)
charge.reverse 課金が取消された時 (マニュアルキャプチャー設定の場合)
charge.update 課金が更新された時

顧客に関するイベント

Event Name Trigger
customer.create 顧客が作成された時
customer.destroy 顧客が削除された時
customer.update 顧客が更新された時
customer.update.card 顧客がカード情報を更新した時(顧客を通じて暗黙のうちに)

チャージバック(dispute)に関するイベント

Event Name Trigger
dispute.accept チャージバックが受け入れられた時
dispute.close チャージバックの結果が出た時
dispute.create チャージバックが開始した時
dispute.update チャージバックが更新された時
Event Name Trigger
link.create リンクが作成された時

受取口座に関するイベント

Event Name Trigger
recipient.activate 受取口座が有効化された時
recipient.create 受取口座が作成された時
recipient.deactivate 受取口座が無効化された時
recipient.destroy 受取口座が削除された時
recipient.update 受取口座が更新された時
recipient.verify 受取口座が承認された時

返金に関するイベント

Event Name Trigger
refund.create 返金が作成された時

スケジュールに関するイベント

Event Name Trigger
schedule.create スケジュールが作成された時
schedule.destroy スケジュールが削除された時
schedule.expire スケジュールの有効期限が切れた時
schedule.expiring スケジュールの有効期限がまもなく切れた時
schedule.suspend スケジュールが停止された時

振込に関するイベント

Event Name Trigger
transfer.create 振込が作成された時
transfer.destroy 振込が削除された時
transfer.fail 振込が失敗とマークされた時
transfer.pay 振込が完了とマークされた時
transfer.send 振込が送信済みとマークされた時
transfer.update 振込が更新された時

動的Webhook

Opn Paymentsのアカウントには、単一の設定可能な静的Webhookが備わっています。デフォルトでは、すべてのイベント通知がこの単一のWebhookエンドポイントに送られます。

動的Webhook機能では、課金作成時にwebhook_endpointsパラメーターを指定することができます。該当する課金に関連するイベントは、指定のwebhook_endpointsに送られます。

webhook_endpoints パラメーターを指定すると、 該当する課金に関連するすべてのイベント通知が webhook_endpointsに送られ、静的Webhookには送られません。

課金作成時にwebhook_endpointsパラメーターが指定されていない場合、イベント通知はアカウントの静的webhookに送信されます。

Omiseは、お客様のウェブサイト全般における利便性を向上するためにクッキーを利用し、お客様のアクセス、閲覧履歴に関する情報を収集します。 当社のウェブサイトを閲覧し続けることにより、お客様は当社のプライバシーポリシーに同意することとします。 詳細はこちら