Webhooks - Fluz

Webhooks 讓你的應用程式在 Fluz 平台發生事件時即時接收通知。你不必輪詢變更，只要註冊一個 HTTPS 端點，Fluz 就會在事件發生當下推送資料給你——例如虛擬卡交易、被拒絕的消費、完成的存款、使用者透過 OAuth 連結其帳戶，等等。

本頁涵蓋所有 webhook 事件，跨越多個平台領域（交易活動、存款、元件流程，以及 OAuth 帳戶連結），而非僅屬於任何單一功能。

Webhooks 適用於 Fluz 平台上的所有應用程式類型：在你自己帳戶上運作的私人應用、代表其他使用者透過 API 行動的公共 OAuth 應用，以及內嵌元件應用。

運作方式

在開發者入口網站為你的應用程式註冊 webhook URL。
選擇要監聽的事件類型（或訂閱全部）。
當相符事件發生時，Fluz 會以 HTTP POST 將已簽章的 JSON 負載送至你的 URL。
你的伺服器驗證簽章、以 2xx 確認並處理該事件。

如果你的端點無法連線或回傳錯誤，Fluz 會在放棄該次投遞前，最多以指數退避重試5 次。

依應用程式類型的 Webhooks

事件如何路由至你的應用，取決於你的應用程式模型。

私人應用 — 你的自有帳戶

Webhooks 會針對你的自有帳戶的活動觸發。你所擁有的帳戶上任何交易、拒絕、或存款，皆會觸發註冊於你應用上的 webhooks。 常見使用情境： 當虛擬卡交易被授權或結算時的通知；即時拒絕警示；監控消費帳戶的存款與餘額變動。

公共應用（OAuth）— 代表使用者行動

Webhooks 會針對已授權你的應用之帳戶的活動觸發。當使用者透過 OAuth 授與你的應用存取權時，只要其 OAuth 授權包含所需的範圍，該使用者的事件就會路由到你註冊的 webhooks。無論該使用者透過你的直接 API 整合或內嵌元件互動皆然；關鍵是使用者與你的應用之間存在 OAuth 關係。 常見使用情境： 知道使用者已將帳戶連結（或重新連結）至你的應用；監控已連結帳戶的虛擬卡消費；即時拒絕通知；追蹤存款完成；接收 KYC 狀態更新。元件應用是特殊的公共應用。事件會以相同方式路由（基於 OAuth 關係），且元件應用另外支援如轉帳完成與禮品卡購買等元件專屬事件。

事件類型

Fluz 僅在你的應用——以及對公共/OAuth 應用而言，個別使用者的 OAuth 授權——擁有所需範圍時傳遞事件。對於沒有必需範圍的事件（例如 OAUTH_USER_LINKED），任何已訂閱的公共/OAuth 應用都會收到。

交易事件

涵蓋完整交易生命週期。適用於所有應用程式類型。

Event	Description	Required scopes
`TRANSACTION_CREATE`	已建立新交易（例如，虛擬卡消費、存款、轉帳）。	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_UPDATE`	交易的狀態或金額已變更（例如已結算、已調整）。	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_DECLINE`	交易被拒絕（例如餘額不足、卡片控管）。	`LIST_PAYMENT`, `LIST_PURCHASES`

存款事件

Event	Description	Required scopes
`DEPOSIT_COMPLETE`	從資金來源至消費帳戶的存款已完成。	`MAKE_DEPOSIT`

OAuth 事件

適用於公共/OAuth 與元件應用。

Event	Description	Required scopes
`OAUTH_USER_LINKED`	使用者已完成與你的應用的 OAuth 連結。初次連結及後續更新（例如授與範圍改變）均會觸發。	None

OAUTH_USER_LINKED 僅傳遞至公共/OAuth 類型應用——私人應用訂閱者不會收到。因其沒有範圍需求，你會對每位連結或重新連結至你應用的使用者收到該事件，無論他們授與哪些範圍。用它來佈建或更新你本地的已連結使用者記錄、擷取授與的範圍集合，並透過 externalReferenceId 對應你自己的使用者識別碼。

元件專屬事件

適用於使用者透過 Fluz 內嵌流程互動的元件與 OAuth 整合。

Event	Description	Required scopes
`WIDGET_KYC_INITIATION`	使用者啟動身分驗證（KYC）。	`VERIFY_KYC`
`WIDGET_DEPOSIT_COMPLETE`	從顧客到你應用的轉帳已完成。	`MAKE_PAYOUT_TRANSFER_SEND`
`WIDGET_WITHDRAW_COMPLETE`	從你應用到顧客的轉帳已完成。	`MAKE_PAYOUT_TRANSFER_RECEIVE`
`WIDGET_PURCHASE_GIFT_CARD`	禮品卡購買已完成。	`PURCHASE_GIFTCARD`

📘 命名說明： WIDGET_DEPOSIT_COMPLETE 與 WIDGET_WITHDRAW_COMPLETE 描述的是顧客↔應用的「轉帳」；DEPOSIT/WITHDRAW 的措辭是歷史沿用。請將「deposit」視為「顧客 → 應用」、「withdraw」視為「應用 → 顧客」。

設定 webhooks

1. 開啟開發者入口網站

前往 Developer Portal 並選擇你的應用程式。

2. 開啟 Webhooks 區段

OAuth 應用： OAuth 分頁 → Webhook URLs。
元件應用： Widget 分頁 → Webhook URLs。
API / 私人應用： 應用設定中的 Webhook URLs 區段。

3. 新增 webhook URL

點擊 Add new URL，輸入你的 HTTPS 端點（例如 https://api.yourapp.com/webhooks/fluz）。

4. 選擇事件

選擇你想接收的事件類型。

5. 儲存

點擊 Create Webhook。你的端點會立即開始接收事件。

管理 webhooks

多個端點 — 你可以為每個應用註冊多個 webhook URL。
變更訂閱事件 — 刪除該 webhook，並以新的事件選擇重新建立。
移除 webhook — 點擊其旁的 Remove。該 webhook 會立即封存並停止接收事件。

接收 webhooks

請求格式

每個 webhook 以 HTTP POST 傳遞，並包含以下標頭：

Header	Description
`Content-Type`	一律為 `application/json`。
`X-HMAC-Signature`	以你的應用 API 金鑰簽署之原始 JSON 內文的 HMAC-SHA256 簽章。
`X-Event-ID`	此事件的唯一 UUID——用於去重。

本文為 JSON 物件，且每個負載都包含 eventType 欄位以識別事件。

端點要求

只允許 HTTPS — 以純 HTTP 的端點會在註冊時被拒。
可公開存取 且能接受 POST 請求。
在 30 秒內以 2xx 回應。 非 2xx 回應或逾時會觸發重試。
驗證每個請求的 HMAC 簽章。

驗證簽章

每次投遞都包含 X-HMAC-Signature 標頭——以你應用的 API 金鑰 對原始 JSON 內文計算之 HMAC-SHA256 雜湊。請務必在信任負載前先加以驗證。

⚠️ 請以原始請求本文驗證。 以 Fluz 傳送的精確位元組來計算 HMAC——請勿對已解析的 JSON 重新序列化。重新字串化可能改變鍵序或空白而導致有效簽章驗證失敗。下列範例為此目的而擷取原始本文。

Node.js (Express)

const express = require('express');
const crypto = require('crypto');
const app = express();
 
// Capture the raw body so the HMAC is computed over the exact bytes Fluz sent.
app.use('/webhooks/fluz', express.raw({ type: 'application/json' }));
 
function verifyFluzWebhook(rawBody, signature, apiKey) {
  const expected = crypto.createHmac('sha256', apiKey).update(rawBody).digest('hex');
  const received = Buffer.from(signature || '', 'hex');
  const computed = Buffer.from(expected, 'hex');
  return received.length === computed.length &&
         crypto.timingSafeEqual(received, computed);
}
 
app.post('/webhooks/fluz', (req, res) => {
  const signature = req.headers['x-hmac-signature'];
  const eventId = req.headers['x-event-id'];
 
  // req.body is a Buffer because of express.raw above
  if (!verifyFluzWebhook(req.body, signature, process.env.FLUZ_API_KEY)) {
    return res.status(401).send('Invalid signature');
  }
 
  // Acknowledge immediately, then process asynchronously
  res.status(200).send('OK');
 
  const event = JSON.parse(req.body.toString('utf8'));
  handleEvent(eventId, event).catch(err =>
    console.error('Webhook processing error:', err)
  );
});

Python (Flask)

import hmac, hashlib
from flask import Flask, request
 
app = Flask(__name__)
 
def verify_fluz_webhook(raw_body: bytes, signature: str, api_key: str) -> bool:
    expected = hmac.new(api_key.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")
 
@app.post("/webhooks/fluz")
def fluz_webhook():
    signature = request.headers.get("X-HMAC-Signature")
    event_id = request.headers.get("X-Event-ID")
 
    # request.get_data() returns the raw bytes — do NOT use request.json for verification
    if not verify_fluz_webhook(request.get_data(), signature, FLUZ_API_KEY):
        return "Invalid signature", 401
 
    enqueue(event_id, request.get_json())  # process asynchronously
    return "OK", 200

回應 webhooks

你的端點必須：

在 30 秒內以 2xx 狀態回應。
迅速回應——先確認，再非同步處理。
可透過 HTTPS 存取。你的端點不得：
回應重新導向（3xx）。
對有效的 webhooks 回應 4xx/5xx（這會觸發重試）。

重試原則

Behavior	Detail
Max attempts	5
Schedule	Exponential backoff
Trigger	Any non-`2xx` response or timeout
Timeout	30 seconds per attempt
After all retries fail	Delivery is abandoned; no further attempts.

當你的端點恢復後，新事件會自動恢復投遞。若要重新傳送已經耗盡重試次數的事件，請聯絡支援並提供相關的 X-Event-ID。

冪等性與順序

Webhooks 可能會被重複投遞，且不保證投遞順序。

使用 X-Event-ID 標頭進行去重。將已處理的 ID 持久化（正式環境可用 Redis 或資料庫），並略過你已處理的事件。
依資料而非到達順序排序。 若順序很重要，請依負載的時間戳（createdAt、updatedAt、transactionDateTime）與事件 ID 排序。

const seen = new Set(); // use Redis or a database in production
 
async function handleEvent(eventId, event) {
  if (seen.has(eventId)) return;  // already processed — skip
  seen.add(eventId);
 
  switch (event.eventType) {
    case 'TRANSACTION_CREATE':    await onTransactionCreated(event); break;
    case 'TRANSACTION_UPDATE':    await onTransactionUpdated(event); break;
    case 'TRANSACTION_DECLINE':   await onTransactionDeclined(event); break;
    case 'DEPOSIT_COMPLETE':      await onDepositComplete(event); break;
    case 'OAUTH_USER_LINKED':     await onUserLinked(event); break;
    case 'WIDGET_KYC_INITIATION': await onKycInitiated(event); break;
    // ...handle remaining widget events
  }
}

識別應用與使用者

使用者： userId 是 Fluz 的使用者 ID。對於 OAuth/元件事件，externalReferenceId 對應到你在 OAuth 流程中的使用者識別碼。
應用： 交易負載包含 connectedAppId 與 connectedAppName。如果你將多個應用路由到同一端點，請以 connectedAppId 分流。對於 OAUTH_USER_LINKED，應用以 appId 識別。

負載參考

每個負載都包含 eventType。欄位可用性會依事件而異；為了前向相容性，處理器應忽略未識別的欄位。

📘 關於 status 值的說明。 對於已建立/已更新的交易，status 欄位會是 PENDING、SETTLED 或 FAILED 之一。被拒交易會帶有 DECLINED（或 FAILED）的 status。本頁早期草稿曾顯示 COMPLETED 作為狀態——實際上不會發出該值；請以 SETTLED 判斷交易已最終完成。

交易已建立（`TRANSACTION_CREATE`）

針對任何新交易觸發——虛擬卡購買、存款、轉帳等。

{
  "eventType": "TRANSACTION_CREATE",
  "recordId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "transactionType": "PURCHASE",
  "amount": 42.99,
  "destination": "Coffee Shop",
  "source": "Virtual Card",
  "status": "PENDING",
  "channel": "VIRTUAL_CARD",
  "connectedAppId": "your-app-id",
  "connectedAppName": "Your App",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "merchantName": "Coffee Shop",
  "merchantCity": "New York",
  "merchantState": "NY",
  "merchantCountry": "US",
  "cardLastFour": "1234",
  "virtualCardId": "vc-uuid-here",
  "cashbackRate": 0.05
}

Field	Type	Description
`eventType`	String	一律為 `TRANSACTION_CREATE`。
`recordId`	String (UUID)	唯一的 webhook 事件記錄 ID。
`transactionId`	String (UUID)	交易 ID。
`accountId`	String (UUID)	Fluz 帳戶 ID。
`userId`	String (UUID)	Fluz 使用者 ID。部分系統產生的交易可能不存在。
`transactionType`	String	交易類型，例如 `PURCHASE`、`GIFT_CARD_PURCHASE`、`DEPOSIT`、`WITHDRAWAL`、`TRANSFER`。請將其視為開放字串。
`amount`	Number	以 USD 計價的交易金額。
`destination`	String	資金去向（例如商家名稱）。
`source`	String	資金來源（例如 `Virtual Card`）。
`status`	String (enum)	`PENDING`、`SETTLED`、`FAILED` 之一。
`channel`	String	交易的來源/通道（例如 `VIRTUAL_CARD`）。請將其視為開放字串。
`connectedAppId`	String	事件所路由至的應用。對私人應用的活動可能不存在。
`connectedAppName`	String	已連結應用的顯示名稱。
`createdAt`	String (ISO 8601)	交易建立時間。
`merchantName` / `merchantCity` / `merchantState` / `merchantCountry`	String	商家所在地詳細資料。
`cardLastFour`	String	使用之卡片的末四碼。
`virtualCardId`	String (UUID)	若適用，虛擬卡 ID。
`cashbackRate`	Number	十進位制現金回饋比率（例如 `0.05` = 5%）。

交易已更新（`TRANSACTION_UPDATE`）

當交易的狀態或細節變更時觸發——例如待授權改為已結算。

{
  "eventType": "TRANSACTION_UPDATE",
  "recordId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "transactionType": "PURCHASE",
  "amount": 42.99,
  "status": "SETTLED",
  "connectedAppId": "your-app-id",
  "connectedAppName": "Your App",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-16T08:00:00.000Z"
}

欄位與 TRANSACTION_CREATE 相同處相同，另包含 updatedAt（ISO 8601）標記變更發生時間。userId、connectedAppId 與 connectedAppName 會如同 TRANSACTION_CREATE 一樣帶出，因此你可以在整個生命週期中一致地識別使用者與應用。status 轉為 SETTLED 表示先前的待處理交易已最終完成。

交易被拒（`TRANSACTION_DECLINE`）

當交易被拒時觸發。包含可供你的應用採取動作的結構化拒絕原因。

{
  "eventType": "TRANSACTION_DECLINE",
  "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "transactionType": "PURCHASE",
  "amount": 500.00,
  "fluzAmount": 500.00,
  "externalFundingAmount": 0,
  "currency": "USD",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DECLINED",
  "merchantName": "Electronics Store",
  "cardLastFour": "1234",
  "virtualCardId": "vc-uuid-here",
  "isCashBalanceUsed": true,
  "isPrepaymentBalanceUsed": false,
  "isRewardsBalanceUsed": false,
  "isReserveBalanceUsed": false,
  "transactionDateTime": "2025-01-15T10:30:00.000Z",
  "declineTitle": "Transaction Declined",
  "declineReason": "Insufficient funds",
  "declineDescription": "Your account balance was not sufficient for this transaction.",
  "declineCategory": "Balance"
}

Field	Type	Description
`amount`	Number	嘗試的總金額。
`fluzAmount`	Number	來自 Fluz 餘額的部分。
`externalFundingAmount`	Number	來自外部資金的部分。
`currency`	String	ISO 貨幣代碼（例如 `USD`）。
`status`	String (enum)	`DECLINED`、`FAILED` 之一。
`userId`	String (UUID)	Fluz 使用者 ID。部分系統產生的交易可能不存在。
`isCashBalanceUsed` / `isPrepaymentBalanceUsed` / `isRewardsBalanceUsed` / `isReserveBalanceUsed`	Boolean	嘗試動用到哪些餘額類型。
`transactionDateTime`	String (ISO 8601)	拒絕發生時間。
`declineTitle`	String	簡短、面向使用者的標題。
`declineReason`	String	簡短原因（例如 `Insufficient funds`）。
`declineDescription`	String	較長、面向使用者的說明。
`declineCtaText`	String	可用時的建議解決行動（例如 `Add money`）。
`declineCategory`	String	高層級拒絕分類。常見值包含 `Balance`、`Limit`、`Validation`、`Virtual Card`、`Acquiring`。請將其視為開放字串，完整清單與各代碼詳情見 Decline Codes。

視交易情況，可能會有其他選用欄位（例如 merchantId、merchantCity、merchantState、merchantCountry、cardDisplayName、virtualCardProgram、channel、bankAccountNickname、bankAccountLastFour）。對於未使用者可忽略。

存款完成（`DEPOSIT_COMPLETE`）

當從資金來源至消費帳戶的存款完成時觸發。

{
  "eventType": "DEPOSIT_COMPLETE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 50.00
}

OAuth 使用者已連結（`OAUTH_USER_LINKED`）

當使用者完成與你的應用的 OAuth 連結時觸發——包含初次連結與後續更新（例如使用者以不同範圍重新授權）。僅適用於公共/OAuth 與元件應用。接收此事件不需要任何範圍。

{
  "eventType": "OAUTH_USER_LINKED",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "appId": "55555555-5555-4555-8555-555555555555",
  "externalReferenceId": "your-reference-123",
  "scopes": [
    "LIST_PAYMENT",
    "MAKE_DEPOSIT"
  ]
}

Field	Type	Description
`eventType`	String	一律為 `OAUTH_USER_LINKED`。
`accountId`	String (UUID)	連結至你應用的 Fluz 帳戶 ID。
`userId`	String (UUID)	連結至你應用的 Fluz 使用者 ID。
`appId`	String (UUID)	你的應用程式 ID。
`externalReferenceId`	String	選用。你在 OAuth 流程中傳遞的使用者識別碼。適用於元件應用類型及任何提供此值的流程；否則可能不存在。
`scopes`	String[]	此使用者授與的去重範圍鍵（例如 `LIST_PAYMENT`、`MAKE_DEPOSIT`）。

由於 OAUTH_USER_LINKED 在重新連結/更新時會再次觸發，請將其視為 upsert：第一次建立已連結使用者，其後每次都更新所儲存的範圍集合。

KYC 啟動（`WIDGET_KYC_INITIATION`）

當使用者開始身分驗證時觸發。僅限公共/元件應用。

{
  "eventType": "WIDGET_KYC_INITIATION",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123"
}

轉帳完成 — 顧客至應用（`WIDGET_DEPOSIT_COMPLETE`）

當使用者將資金轉入你的應用時觸發。

{
  "eventType": "WIDGET_DEPOSIT_COMPLETE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 25.50
}

轉帳完成 — 應用至顧客（`WIDGET_WITHDRAW_COMPLETE`）

當你的應用將資金轉給使用者時觸發。

{
  "eventType": "WIDGET_WITHDRAW_COMPLETE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 15.00
}

禮品卡購買（`WIDGET_PURCHASE_GIFT_CARD`）

當透過元件完成禮品卡購買時觸發。

{
  "eventType": "WIDGET_PURCHASE_GIFT_CARD",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 25.00
}

常見元件負載欄位： userId（Fluz 使用者 ID）、accountId（Fluz 帳戶 ID）、externalReferenceId（你在 OAuth 流程中的使用者識別碼），以及適用時的 amount。

最佳實務

先快速回應，再行處理。 先立即回傳 200，並非同步處理事件，以避免逾時與不必要的重試。
驗證每個請求。 使用你的 API 金鑰，針對原始本文驗證 X-HMAC-Signature 後再處理。
以事件 ID 去重。 追蹤 X-Event-ID 以處理重試/重複投遞。
將類列舉欄位視為開放字串。 新的 transactionType、channel、declineCategory 值可能陸續出現；只針對你關心的值分支，並寬容未知值。
對 OAUTH_USER_LINKED 採用 upsert。 它對每位使用者可能觸發多次；每次都更新已儲存的範圍集合，而非假設只在首次連結觸發。
接受未知欄位。 負載可能隨時間新增欄位；請忽略未識別的欄位而非失敗。
監控你的端點。 對連續非 2xx 回應發出警報——在 5 次嘗試失敗後，該事件的投遞會被放棄。

疑難排解

Symptom	Likely cause	Fix
沒有收到任何 webhooks	端點無法連線或回傳錯誤	確認 URL 正確、可透過 HTTPS 公開存取，且回傳 `2xx`。
少了特定事件類型	應用缺少必要範圍	確認你的應用擁有該事件所列的範圍。
公共應用未收到某使用者的事件	使用者未授與所需範圍	確認該使用者的 OAuth 授權包含所需範圍。
未收到 `OAUTH_USER_LINKED`	在私人應用中訂閱，或未訂閱	此事件僅適用公共/OAuth。請在 OAuth 或元件應用中訂閱（或使用全選）。
簽章驗證失敗	使用錯誤的 API 金鑰，或對重新序列化的本文驗證	使用你應用的 API 金鑰，並以原始請求本文驗證。
收到重複投遞	逾時後的重試	以 `X-Event-ID` 實作冪等性。
事件停止到達	連續 5 次失敗已耗盡重試	修復你的端點；新事件會自動恢復。聯絡支援以重播已耗盡重試的事件。

需要協助？

技術問題： 檢查你的端點日誌，並連絡支援時提供 X-Event-ID。
範圍相關問題： 請參閱 Application Scopes 與 Decline Codes。

​運作方式

​依應用程式類型的 Webhooks

​私人應用 — 你的自有帳戶

​公共應用（OAuth）— 代表使用者行動

​元件應用（Widget apps）

​事件類型

​交易事件

​存款事件

​OAuth 事件

​元件專屬事件

​設定 webhooks

​1. 開啟開發者入口網站

​2. 開啟 Webhooks 區段

​3. 新增 webhook URL

​4. 選擇事件

​5. 儲存

​管理 webhooks

​接收 webhooks

​請求格式

​端點要求

​驗證簽章

​Node.js (Express)

​Python (Flask)

​回應 webhooks

​重試原則

​冪等性與順序

​識別應用與使用者

​負載參考

​交易已建立（TRANSACTION_CREATE）

​交易已更新（TRANSACTION_UPDATE）

​交易被拒（TRANSACTION_DECLINE）

​存款完成（DEPOSIT_COMPLETE）

​OAuth 使用者已連結（OAUTH_USER_LINKED）

​KYC 啟動（WIDGET_KYC_INITIATION）

​轉帳完成 — 顧客至應用（WIDGET_DEPOSIT_COMPLETE）

​轉帳完成 — 應用至顧客（WIDGET_WITHDRAW_COMPLETE）

​禮品卡購買（WIDGET_PURCHASE_GIFT_CARD）

​最佳實務

​疑難排解

​需要協助？

運作方式

依應用程式類型的 Webhooks

私人應用 — 你的自有帳戶

公共應用（OAuth）— 代表使用者行動

元件應用（Widget apps）

事件類型

交易事件

存款事件

OAuth 事件

元件專屬事件

設定 webhooks

1. 開啟開發者入口網站

2. 開啟 Webhooks 區段

3. 新增 webhook URL

4. 選擇事件

5. 儲存

管理 webhooks

接收 webhooks

請求格式

端點要求

驗證簽章

Node.js (Express)

Python (Flask)

回應 webhooks

重試原則

冪等性與順序

識別應用與使用者

負載參考

交易已建立（`TRANSACTION_CREATE`）

交易已更新（`TRANSACTION_UPDATE`）

交易被拒（`TRANSACTION_DECLINE`）

存款完成（`DEPOSIT_COMPLETE`）

OAuth 使用者已連結（`OAUTH_USER_LINKED`）

KYC 啟動（`WIDGET_KYC_INITIATION`）

轉帳完成 — 顧客至應用（`WIDGET_DEPOSIT_COMPLETE`）

轉帳完成 — 應用至顧客（`WIDGET_WITHDRAW_COMPLETE`）

禮品卡購買（`WIDGET_PURCHASE_GIFT_CARD`）

最佳實務

疑難排解

需要協助？