Skip to main content
Webhook を使用して非同期の変更に対応します。配信は少なくとも 1 回であり、重複、遅延、順序の不同のイベントは通常発生します。

必要なイベントのみを登録する

POST /v3/webhooks でエンドポイントを作成します。インテグレーションを駆動する、文書化されたイベントのみを購読してください。この例では transfer.state_changed を使用します。
レスポンスの data.idWEBHOOK_ID として保存します。GET /v3/webhooks/portal が返すポータルを開き、このエンドポイントの署名シークレットを取得して、API キーとは別のシークレットマネージャーに保管してください。

パース前に検証する

Swipelux は、新しい Webhook インテグレーションを Svix 経由で配信します。エンドポイントの署名シークレットと次のヘッダーを使用して、生のリクエストボディを検証してください。
  • svix-id
  • svix-timestamp
  • svix-signature
検証が成功する前に JSON をパースしたり副作用を発生させたりしないでください。
署名がないか無効なリクエストは拒否してください。検証が完了するまで、生のボディを利用可能な状態に保ってください。

永続化し、確認応答し、その後に処理する

エンベロープの id に一意制約を設定します。検証済みのエンベロープを永続化し、2xx を速やかに返し、その後で非同期に処理してください。 イベント ID が既に存在する場合は、完了した副作用を繰り返さずに配信を確認応答してください。保留中または失敗したローカル作業は、独自の再試行キューを通じて再開します。エンベロープの attempt フィールドを重複排除キーやトランスポートの再試行カウンターとして使用しないでください。

現在の状態を再取得する

Webhook の順序は、権威のあるリソース履歴ではありません。resource.typeresource.id を使ってオブジェクトを特定し、システムを更新する前に現在の状態を取得してください。 送金イベントの場合は、GET /v3/transfers/{transferId} を呼び出します。
顧客に表示するステータスと下流のアクションは、現在の API レスポンスから駆動してください。2 つのワーカーが関連イベントを異なる順序で処理しても安全なように副作用を設計してください。

配信をリカバリーする

GET /v3/webhooks/portal を使って、配信ログを開き、失敗した配信を再試行するか、手動再生を開始してください。 すべての再生は、同じ署名検証と耐久性のあるインボックスを通過する必要があります。ダウンタイム後にリカバリーするには、影響を受けた期間を再生し、参照される各リソースを再取得してください。完了したイベント ID はノーオペレーションとなり、未完了のレコードは非同期に再開します。 次に、サンドボックスで重複や順序不同の配信を確認し、本番リリース チェックリストを完了してください。