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 |
チャージバックが更新された時 |
リンク(Link)に関するイベント
| 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に送信されます。
