Skip to main content
Hello Clever の Webhook を使うと、決済のステータスが変わるたびに(たとえば pending から authorised、または authorised から waiting へ移ったときに)サーバーがリアルタイムで通知を受け取れます。API をポーリングする代わりにエンドポイントを登録すれば、ステータスが変わるたびに Hello Clever が自動的に POST リクエストを送信します。

Webhook の仕組み

決済のステータスが変わると、Hello Clever は設定された endpoint_url に対して、取引の現在の状態を示す JSON のペイロードとともに POST リクエストを送信します。受信を確認するため、エンドポイントは HTTP 200 を返す必要があります。返さない場合、Hello Clever は各試行の間に 15 分の間隔を置いて最大3回リトライします。
リトライによって同じペイロードが複数回配信される可能性があるため、Webhook のエンドポイントでは冪等な処理を実装してください。イベントの重複排除には uuid の項目を使ってください。

Webhook の設定

Webhook のエンドポイントは2つの方法で設定できます。 SDK 連携:既定の Webhook の URL を登録するには Hello Clever へご連絡ください。SDK 経由で作成されたすべての決済がその URL へ通知を送信します。 API 連携:決済作成のリクエストに webhook_notification のオブジェクトを含めます。指定した場合、その決済については既定の Webhook の URL を上書きします。
object
決済作成のリクエストに含める Webhook の設定です。

決済のステータス

Hello Clever は、決済が次のいずれかのステータスに移るたびに Webhook の通知を送信します。
決済が in_dispute のステータスにある場合、異議解決の手続きに証拠を提出するため、Hello Clever のサポートへご連絡ください。

Webhook のオブジェクト

各 Webhook の POST のボディには次の項目が含まれます。

ペイロードの例

オーソリ済みカードのトークン

カード決済が authorised または waiting のステータスに達すると、Hello Clever は Webhook のペイロードに token のオブジェクトを含めます。このトークンは安全に保管してください。同じ顧客に対して、カード情報の再入力を求めずに将来の決済を作成できます。
token のオブジェクトが Webhook の通知に含まれるのは、ステータスが authorised または waiting に変わったときのみです。それ以外のステータスの通知には含まれません。

Webhook のセキュリティ

Hello Clever は2つのセキュリティの仕組みに対応しており、単独でも併用でも利用できます。

Authorization ヘッダー

Webhook の設定で authorization_header を指定すると、Hello Clever はエンドポイントへのすべての Webhook リクエストの Authorization ヘッダーでその値を送信します。
サーバー側でこのヘッダーを既知のシークレットと照合し、リクエストが Hello Clever からのものであることを確認してください。

HTTP Webhook 署名 (HMAC-SHA256)

Hello Clever は各 Webhook のペイロードを HMAC-SHA256 で署名し、その署名を HTTP-WEBHOOK-SIGNATURE のヘッダーで送信します。
署名を検証するには、Webhook Secret Key を使って生のリクエストボディの HMAC-SHA256 を再計算し、ヘッダーの値と比較してください。
1

Webhook Secret Key を確認する

Merchant Portal で Dashboard → Developer → Authentication → Webhook タブへ移動し、Webhook secret key の欄の値をコピーします。
2

想定される署名を計算する

生のリクエストボディ(JSON をパースして再度文字列化しないこと)と Webhook Secret Key を使います。
3

比較して受け入れるか拒否する

署名が一致すれば、ペイロードは正当で改変されていません。異なる場合はリクエストを拒否してください。改ざんされている、または信頼できない送信元から送られた可能性があります。
セキュリティを最大化するには、Authorization ヘッダーと HTTP-WEBHOOK-SIGNATURE の両方を検証してください。Authorization ヘッダーは送信者を確認し、署名はペイロードが改ざんされていないことを確認します。

エラー処理とリトライ

エンドポイントが HTTP 200 を返さない場合、Hello Clever は各試行の間に 15 分の間隔を置いて、Webhook の呼び出しを最大 3 回リトライします。 リトライを正しく扱うには次のようにしてください。
  • 重い処理を行う前に、Webhook を受け取った時点で直ちに 200 を返してください。
  • タイムアウトを避けるため、イベントは非同期に処理してください(キューを使うなど)。
  • 重複した配信を検出して破棄するため、uuid の項目を使ってください。

エラーコード

決済が失敗すると、pay_code のオブジェクトに error_codeerror_message が含まれます。次の表はすべてのエラーコードの一覧です。

ベストプラクティス

  1. 処理を行う前に、すべての受信リクエストで Authorization ヘッダーまたは HTTP-WEBHOOK-SIGNATURE を検証してください。
  2. リトライによる副作用の重複を防ぐため、uuid の項目を使って冪等性を実装してください。
  3. リクエストを受け取ったら直ちに 200 OK を返し、ペイロードは非同期に処理してください。
  4. Webhook のエンドポイントの URL は非公開に保ち、公開の場での共有は避けてください。
  5. 通信中のペイロードを保護するため、Webhook のエンドポイントには HTTPS を使ってください。
  6. 開発中は webhook.sitengrok のようなローカルトンネルを使ってエンドポイントをテストしてください。