Webhook

使用 webhook 對非同步變更作出反應。派送是至少一次(at least once)保證,因此重複、延遲與亂序的事件皆屬正常。

僅註冊您需要的事件

使用 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 本身即可授予存取權,且會在一小時後到期,因此請每次重新要求,切勿儲存或分享。入口網站依資源將 v3 事件分組:Customers、Capabilities、Accounts、Recipients、Transfers 與 API。每個事件都會顯示其 payload 結構描述與範例。舊版事件會標示為已淘汰,且列在獨立的 Legacy 群組中。若您的端點已訂閱某個舊版事件,仍會持續收到該事件。新的訂閱請選擇 v3 事件名稱。

變更端點的事件

使用 GET /v3/webhooks/{webhookId} 讀取單一端點。回應的 events 結構與 GET /v3/webhooks 相同,且絕不包含簽章密鑰。讀取需要 webhooks:read,若端點 ID 不存在則回傳 404 not_found。使用 PATCH /v3/webhooks/{webhookId} 更新端點。請傳送 Idempotency-Key 標頭。更新需要 webhooks:write。

僅傳送 events,即可保留目前的 URL。
僅傳送 url,即可保留目前選取的事件。
events 會取代整個選取範圍。請先讀取端點,並納入您仍需要的每個事件。
新的訂閱必須使用 v3 事件名稱。
若端點已訂閱某個舊版事件名稱,您可以保留它。新增舊版名稱會回傳 400 validation_error。

以下請求主體會保留 URL 並取代選取的事件:

Request body

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

解析前先驗證

Swipelux 透過 Svix 派送新的 webhook 整合。請使用您的端點簽章密鑰以及以下標頭驗證原始請求主體:

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 回應驅動面向客戶的狀態與後續動作。設計副作用時,即使兩個 worker 以不同順序處理相關事件,也應保持安全。

復原派送

使用 GET /v3/webhooks/portal 開啟派送日誌。具有 webhooks:write 時,您也可以重試失敗派送或啟動手動重播。僅具有 webhooks:read 的金鑰所開啟的入口網站只會顯示派送記錄,無法重試、重播或顯示簽章密鑰。每次重播皆須經過相同的簽章驗證與可靠收件匣。若欲於停機後復原,請重播受影響的時段,並重新讀取每個所引用的資源。已完成的事件 ID 會保持無操作;未完成的紀錄則會以非同步方式繼續。接下來,請於沙箱中驗證重複與亂序派送,然後完成上線清單。

開始使用

客戶引導

建立金流

上線

僅註冊您需要的事件

變更端點的事件

解析前先驗證

保存、確認,然後處理

重新讀取當前狀態

復原派送

​僅註冊您需要的事件

​變更端點的事件

​解析前先驗證

​保存、確認,然後處理

​重新讀取當前狀態

​復原派送

僅註冊您需要的事件

變更端點的事件

解析前先驗證

保存、確認,然後處理

重新讀取當前狀態

復原派送