Webhook

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

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

POST /v3/webhooks でエンドポイントを作成します。インテグレーションを駆動する、文書化されたイベントのみを購読してください。この例では transfer.state_changed を使用します。

Create webhook endpoint

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_API_KEY='replace-with-your-api-key'

curl --request POST \
  "${API_BASE}/v3/webhooks" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: webhook-endpoint-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "url": "https://example.com/webhooks/swipelux",
  "events": ["transfer.state_changed"]
}
JSON

レスポンスの data.id を WEBHOOK_ID として保存します。webhooks:write を持つ API キーで GET /v3/webhooks/portal からポータル URL をリクエストし、このエンドポイントの署名シークレットを取得して、API キーとは別のシークレットマネージャーに保管してください。ポータル URL はそれ自体でアクセス権を付与し、1 時間で有効期限が切れます。そのため、毎回新しい URL をリクエストし、保存や共有はしないでください。ポータルでは、v3 のイベントがリソースごとにグループ化されています: Customers、Capabilities、Accounts、Recipients、Transfers、API。各イベントには、ペイロードスキーマと例が表示されます。レガシーイベントは非推奨としてマークされ、別の Legacy グループに一覧表示されます。エンドポイントがすでにレガシーイベントを購読している場合、そのイベントは引き続き受信されます。新しい購読には v3 のイベント名を選択してください。

エンドポイントのイベントを変更する

GET /v3/webhooks/{webhookId} で 1 つのエンドポイントを読み取ります。レスポンスは GET /v3/webhooks と同じ events の形式です。署名シークレットが含まれることはありません。読み取りには webhooks:read が必要で、不明なエンドポイント ID に対しては 404 not_found を返します。 PATCH /v3/webhooks/{webhookId} でエンドポイントを更新します。Idempotency-Key ヘッダーを送信してください。更新には webhooks:write が必要です。

現在の URL を維持するには、events のみを送信します。
現在のイベント選択を維持するには、url のみを送信します。
events は選択全体を置き換えます。先にエンドポイントを読み取り、引き続き必要なすべてのイベントを含めてください。
新しい購読には v3 のイベント名を使用する必要があります。
エンドポイントがすでに購読しているレガシーイベント名は維持できます。新しいレガシー名を追加すると 400 validation_error が返されます。

次のボディは URL を維持し、選択を置き換えます。

Request body

{
  "events": ["transfer.state_changed", "capability.status_changed"]
}

パース前に検証する

Swipelux は、新しい Webhook インテグレーションを Svix 経由で配信します。エンドポイントの署名シークレットと次のヘッダーを使用して、生のリクエストボディを検証してください。

svix-id
svix-timestamp
svix-signature

検証が成功する前に JSON をパースしたり副作用を発生させたりしないでください。

Verify signature

import { Webhook } from "svix";

const verifier = new Webhook(process.env.SWIPELUX_WEBHOOK_SECRET);

export async function handleSwipeluxWebhook(request) {
  const rawBody = await request.text();
  const event = verifier.verify(rawBody, {
    "svix-id": request.headers.get("svix-id"),
    "svix-timestamp": request.headers.get("svix-timestamp"),
    "svix-signature": request.headers.get("svix-signature"),
  });

  await webhookInbox.insertIfAbsent({
    id: event.id,
    payload: event,
    status: "pending",
  });

  return new Response(null, { status: 204 });
}

署名がないか無効なリクエストは拒否してください。検証が完了するまで、生のボディを利用可能な状態に保ってください。

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

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

現在の状態を再取得する

Webhook の順序は、権威のあるリソース履歴ではありません。resource.type と resource.id を使ってオブジェクトを特定し、システムを更新する前に現在の状態を取得してください。送金イベントの場合は、GET /v3/transfers/{transferId} を呼び出します。

Refetch transfer

curl --request GET \
  "${API_BASE}/v3/transfers/${TRANSFER_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

顧客に表示するステータスと下流のアクションは、現在の API レスポンスから駆動してください。2 つのワーカーが関連イベントを異なる順序で処理しても安全なように副作用を設計してください。

配信をリカバリーする

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

はじめに

顧客のオンボーディング

資金フローの構築

ローンチ

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

エンドポイントのイベントを変更する

パース前に検証する

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

現在の状態を再取得する

配信をリカバリーする

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

​エンドポイントのイベントを変更する

​パース前に検証する

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

​現在の状態を再取得する

​配信をリカバリーする

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

エンドポイントのイベントを変更する

パース前に検証する

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

現在の状態を再取得する

配信をリカバリーする