Webhooks（Webhook）

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

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

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

運作方式

在 Developer Portal 中為你的應用程式註冊一個 webhook URL。
選擇要監聽的事件類型（或訂閱全部事件）。
當符合的事件發生時，Fluz 會以 HTTP POST 將已簽名的 JSON 載荷傳送至你的 URL。
你的伺服器驗證簽章、以 2xx 確認接收，並處理該事件。

若你的端點無法連線或回傳錯誤，Fluz 會採用指數退避最多重試 5 次，之後才放棄該次投遞。

依應用程式類型的 Webhook 行為

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

私人應用 — 你的自有帳戶

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

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

Webhook 會針對「已授權你的應用」之帳戶的活動觸發。當使用者透過 OAuth 授予你的應用存取權時，他們的事件就會路由至你註冊的 webhook——前提是該使用者的 OAuth 授權包含必要的 scopes。無論使用者透過你的直接 API 串接或內嵌 widget 互動都適用；關鍵是使用者與你的應用之間存在 OAuth 關係。 常見使用情境： 知道使用者已連結（或重新連結）其帳戶至你的應用；監控已連結帳戶的虛擬卡消費；即時拒絕通知；追蹤存款完成；接收 KYC 狀態更新。 Widget 應用是特殊的公開應用。事件路由機制相同（基於 OAuth 關係），此外還支援 widget 特有事件，例如轉帳完成與禮品卡購買。

事件類型

Fluz 僅在你的應用——以及對於公開/OAuth 應用來說，個別使用者的 OAuth 授權——擁有所需 scopes 時才會投遞事件。無需任何 scope 的事件（例如 OAUTH_USER_LINKED）會投遞給任何已訂閱的公開/OAuth 應用。

交易事件

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

事件	說明	必要 scopes
`TRANSACTION_CREATE`	建立了新交易（例如，虛擬卡消費、存款、轉帳）。	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_UPDATE`	交易的狀態或金額變更（例如入帳、調整）。	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_DECLINE`	交易遭到拒絕（例如餘額不足、卡片控制）。	`LIST_PAYMENT`, `LIST_PURCHASES`

存款事件

事件	說明	必要 scopes
`DEPOSIT_COMPLETE`	從資金來源到消費帳戶的存款已完成。	`MAKE_DEPOSIT`

OAuth 事件

適用於「公開/OAuth 與 widget 應用」。

事件	說明	必要 scopes
`OAUTH_USER_LINKED`	使用者完成將其帳戶透過 OAuth 連結至你的應用。會在初次連結與後續更新（例如授權 scopes 變更）時觸發。	無

OAUTH_USER_LINKED 僅投遞至公開/OAuth 類型應用——私人應用的訂閱者不會接收。由於它沒有 scope 要求，你會對每一位連結或重新連結至你應用的使用者收到該事件，無論他們授與哪些 scopes。使用此事件以建立或更新你本地的已連結使用者記錄、擷取授與的 scope 集合，並透過 externalReferenceId 對應你自己的使用者識別碼。適用於使用者透過 Fluz 內嵌流程互動的 widget 與 OAuth 整合。

事件	說明	必要 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」視為「應用 → 客戶」。

設定 webhook

1. 開啟 Developer Portal

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

2. 開啟 Webhooks 區段

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

3. 新增 webhook URL

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

4. 選擇事件

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

5. 儲存

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

管理 webhook

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

接收 webhook

請求格式

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

標頭	說明
`Content-Type`	一律為 `application/json`。
`X-HMAC-Signature`	以你的應用 API key 簽署之原始 JSON 本文的 HMAC-SHA256 簽章。
`X-Event-ID`	該事件的唯一 UUID——用於去重。

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

端點要求

僅限 HTTPS — 純 HTTP 端點在註冊時即會被拒絕。
可公開存取，且能接受 POST 請求。
在 30 秒內以 2xx 回應。 非 2xx 回應或逾時會觸發重試。
在每次請求上驗證 HMAC 簽章。

驗證簽章

每次投遞都包含 X-HMAC-Signature 標頭——這是以你的應用「API key」對「原始」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

回應 webhook

你的端點「必須」：

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

重試策略

行為	詳細
最大嘗試次數	5
排程	指數退避
觸發條件	任何非 `2xx` 回應或逾時
逾時	每次嘗試 30 秒
全部重試失敗後	放棄投遞；不再嘗試。

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

冪等性與順序

Webhook 可能「重複投遞」，且「不保證投遞順序」。

使用 X-Event-ID 標頭進行「去重」。在正式環境中以 Redis 或資料庫持久化已處理的 ID，並略過已處理的事件。
「依資料排序而非抵達順序。」若順序有關，請依據載荷時間戳（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/widget 事件，externalReferenceId 會對應到你在 OAuth 流程中的「自家使用者識別碼」。
應用： 交易載荷包含 connectedAppId 與 connectedAppName。若你將多個應用路由至同一端點，請根據 connectedAppId 分支處理。對於 OAUTH_USER_LINKED，應用會以 appId 識別。

載荷參考

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

📘 關於 status 值的說明。 對於建立/更新的交易，status 欄位可能為 PENDING、SETTLED、或 FAILED。遭拒的交易其 status 為 DECLINED（或 FAILED）。本頁早期草稿曾顯示 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",
  "digitalWalletProvider": "APPLE_PAY",
  "digitalWalletToken": "dw_2204zdpwi8352fa1jvhs2nl0ikgvdgnism",
  "cashbackRate": 0.05
}

欄位	型別	說明
`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。
`digitalWalletProvider`	String (enum)	當交易透過行動錢包進行時會出現。可能為 `APPLE_PAY`、`GOOGLE_PAY`（未來可能新增）。對非錢包交易為缺省或 `null`。此欄位用來判定交易是否為行動錢包付款。
`digitalWalletToken`	String	代碼化卡片的網路代碼識別碼（例如 `dw_...`）。本身不是錢包指標：對於非錢包的網路代碼（例如商家儲存的卡片）也會設定，且在部分錢包交易中可能不存在。請使用 `digitalWalletProvider`，而非此代碼是否存在，來判定是否為行動錢包付款。
`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"
}

欄位	型別	說明
`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`。視為開放字串；完整清單與各代碼細節請參見拒絕代碼。

視交易而定，可能出現其他選用欄位（例如 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 連結至你的應用時觸發——包含初次連結與後續更新（例如使用者以不同的 scope 集合重新授權）。僅適用於公開/OAuth 與 widget 應用。接收此事件不需任何 scope。

{
  "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"
  ]
}

欄位	型別	說明
`eventType`	String	一律為 `OAUTH_USER_LINKED`。
`accountId`	String (UUID)	連結至你應用的 Fluz 帳戶 ID。
`userId`	String (UUID)	連結至你應用的 Fluz 使用者 ID。
`appId`	String (UUID)	你的應用程式 ID。
`externalReferenceId`	String	「選用」。你在 OAuth 流程中傳遞的自家使用者識別碼。對於 widget 應用與任何有提供者會出現；否則可能缺省。
`scopes`	String[]	該使用者授與的去重後 scope 鍵（例如 `LIST_PAYMENT`、`MAKE_DEPOSIT`）。

由於 OAUTH_USER_LINKED 在重新連結/更新時也會觸發，請將其視為 upsert：首次接收時建立已連結使用者，後續接收時更新儲存的 scope 集合。

啟動 KYC（`WIDGET_KYC_INITIATION`）

當使用者開始身分驗證時觸發。僅適用於公開/widget 應用。

{
  "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`）

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

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

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

最佳實務

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

疑難排解

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

需要協助？

技術問題： 檢查你的端點日誌，並連絡支援時附上 X-Event-ID。
scope 相關問題： 請參見應用程式 Scopes 與拒絕代碼。

​運作方式

​依應用程式類型的 Webhook 行為

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

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

​Widget 應用

​事件類型

​交易事件

​存款事件

​OAuth 事件

​Widget 特有事件

​設定 webhook

​1. 開啟 Developer Portal

​2. 開啟 Webhooks 區段

​3. 新增 webhook URL

​4. 選擇事件

​5. 儲存

​管理 webhook

​接收 webhook

​請求格式

​端點要求

​驗證簽章

​Node.js (Express)

​Python (Flask)

​回應 webhook

​重試策略

​冪等性與順序

​辨識應用與使用者

​載荷參考

​交易建立（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）

​最佳實務

​疑難排解

​需要協助？

運作方式

依應用程式類型的 Webhook 行為

私人應用 — 你的自有帳戶

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

Widget 應用

事件類型

交易事件

存款事件

OAuth 事件

Widget 特有事件

設定 webhook

1. 開啟 Developer Portal

2. 開啟 Webhooks 區段

3. 新增 webhook URL

4. 選擇事件

5. 儲存

管理 webhook

接收 webhook

請求格式

端點要求

驗證簽章

Node.js (Express)

Python (Flask)

回應 webhook

重試策略

冪等性與順序

辨識應用與使用者

載荷參考

交易建立（`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`）

最佳實務

疑難排解

需要協助？