Webhooks（Webhook）

Webhook 讓你的應用程式在 Fluz 平台上發生事件時即時接收通知。你不需要輪詢變更，而是註冊一個 HTTPS 端點，Fluz 會在事件發生的當下把事件資料推送給你——例如虛擬卡交易、被拒絕的購買、完成的入金，等等。

本頁作為 Webhooks 的頂層說明，因為 webhook 事件跨越多個平台區域（元件流程與交易活動），而不是屬於單一功能。

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

運作方式

在開發者入口註冊你的應用程式的 webhook URL。
選擇你要接收的事件類型（或訂閱全部）。
當符合的事件發生時，Fluz 會以帶簽章的 JSON 有效負載發出 HTTP POST 至你的 URL。
你的伺服器驗證簽章、以 2xx 回應並處理事件。

如果你的端點無法使用或回傳錯誤，Fluz 會採用指數退避最多重試 5 次，之後才將事件標記為 FAILED。

依應用程式類型的 Webhooks

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

私人應用 — 你的自有帳戶

Webhooks 會針對發生在「你的自有帳戶」上的活動觸發。任何你擁有的帳戶上的交易、拒絕、或入金，都會觸發註冊在你應用上的 webhooks。 常見使用情境： 當虛擬卡交易被授權或結算時的通知；即時拒絕提醒；監控你的消費帳戶的入金與餘額變動。

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

Webhooks 會針對「已授權你的應用」之帳戶的活動觸發。當使用者透過 OAuth 授權你的應用存取，他們的事件就會路由至你註冊的 webhooks——前提是該使用者的 OAuth 授權涵蓋必要的範圍（scopes）。無論使用者是經由你直接的 API 串接或嵌入式元件互動都適用；關鍵是使用者與你的應用之間存在 OAuth 關係。 常見使用情境： 監控已連結帳戶的虛擬卡消費；即時拒絕通知；追蹤入金完成；接收 KYC 狀態更新。元件應用是特殊的公用應用。事件以相同方式路由（基於 OAuth 關係），且元件應用另外支援元件專屬事件，例如轉帳完成與禮品卡購買。

事件類型

只有在你的應用——以及對於公用/OAuth 應用，個別使用者的 OAuth 授權——持有所需的範圍（scopes）時，Fluz 才會傳送事件。

交易事件

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

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`

元件專屬事件

適用於使用者透過 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. 選取事件

選擇你想接收的事件類型。將選取留空可作為接收全部，你會收到你的應用具備 scope 的所有事件。

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	指數退避
Trigger	任何非 `2xx` 回應或逾時
Timeout	每次嘗試 30 秒
After all retries fail	事件標記為 `FAILED`；不再嘗試投遞。
Logging	每次嘗試都會個別記錄以供稽核。

當你的端點恢復時，新事件會自動恢復投遞。若要重新傳送已達到 FAILED 的事件，請與客服聯繫並提供相關的 X-Event-ID。

事件狀態生命週期

Status	Meaning
`CREATED`	事件已記錄並排入佇列。
`IN_PROGRESS`	正在比對 webhook 訂閱。
`NO_SUBSCRIBERS`	沒有符合此事件的有效 webhooks。
`SUCCESS`	投遞成功。
`FAILED`	已耗盡所有重試次數。

冪等性與順序

Webhooks 可能會被「投遞多次」，且「不保證投遞順序」。

使用 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 'WIDGET_KYC_INITIATION': await onKycInitiated(event); break;
    // ...handle remaining widget events
  }
}

辨識應用與使用者

使用者： userId 是 Fluz 使用者 ID。對於 OAuth/元件事件，externalReferenceId 對應於你在 OAuth 流程中的使用者識別符。
應用： 交易有效負載包含 connectedAppId 與 connectedAppName。如果你把多個應用路由到同一端點，請依 connectedAppId 分支處理。

有效負載參考

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

交易已建立（`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": "COMPLETED",
  "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 (enum)	例如 `PURCHASE`。(需確認完整集合。)
`amount`	Number	交易金額（USD）。
`destination`	String	資金去向（如商家名稱）。
`source`	String	資金來源（例如 `Virtual Card`）。
`status`	String (enum)	例如 `COMPLETED`。(需確認完整集合——如 `PENDING`、`SETTLED`、`DECLINED`。)
`channel`	String (enum)	例如 `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",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-16T08:00:00.000Z"
}

欄位在可用時與 TRANSACTION_CREATE 對應，並新增 updatedAt（ISO 8601）表示變更發生時間。

🚧 一致性檢查： 請確認 TRANSACTION_UPDATE（與 TRANSACTION_DECLINE）是否也包含 userId 與 connectedAppId/connectedAppName，以便使用方能在整個生命週期一致識別使用者與應用。

交易被拒絕（`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	`DECLINED`。
`isCashBalanceUsed` / `isPrepaymentBalanceUsed` / `isRewardsBalanceUsed` / `isReserveBalanceUsed`	Boolean	嘗試動用的餘額類型。
`transactionDateTime`	String (ISO 8601)	拒絕發生時間。
`declineTitle`	String	短的、面向使用者的標題。
`declineReason`	String	簡短原因（例如 `Insufficient funds`）。
`declineDescription`	String	較長、面向使用者的說明。
`declineCategory`	String (enum)	例如 `BALANCE`。(確認完整集合——參見 Decline Codes。)

入金完成（`DEPOSIT_COMPLETE`）

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

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

啟動 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`）

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

🚧 待補充。 請新增 WIDGET_PURCHASE_GIFT_CARD 的有效負載範例與欄位表（例如商家、金額、禮品卡識別碼）。

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

最佳實務

快速回應，稍後處理。 立即回傳 200，並以非同步方式處理事件，以避免逾時與不必要的重試。
驗證每個請求。 使用你的 API 金鑰，針對原始本文驗證 X-HMAC-Signature 後再處理。
以事件 ID 去重。 追蹤 X-Event-ID 以處理重試/重複投遞。
接受未知欄位。 有效負載可能隨時間新增欄位；忽略未識別欄位而非失敗。
監控你的端點。 對連續的非 2xx 回應發出警報——在 5 次失敗後事件會被標記為 FAILED。

疑難排解

Symptom	Likely cause	Fix
沒有收到任何 webhooks	端點無法連線或回傳錯誤	確認 URL 正確、可透過 HTTPS 公開存取，且回傳 `2xx`。
少了某些事件類型	應用缺少必要的 scopes	確保你的應用持有所列事件所需的 scopes。
公用應用未收到某使用者的事件	使用者未授與必要的 scopes	確認該使用者的 OAuth 授權包含所需 scopes。
簽章驗證失敗	錯誤的 API 金鑰，或對重新序列化的本文驗證	使用你的應用 API 金鑰，並針對原始請求本文驗證。
收到重複投遞	逾時後的重試	以 `X-Event-ID` 實作冪等性。
事件停止傳送	連續 5 次失敗已耗盡重試	修復你的端點；新事件會自動恢復。聯絡客服以重播 `FAILED` 事件。

需要協助？

技術問題： 請檢查你的端點日誌，並提供 X-Event-ID 與客服聯繫。
Scope 相關問題： 參見 Application Scopes 與 Decline Codes。

​運作方式

​依應用程式類型的 Webhooks

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

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

​元件應用（Widget apps）

​事件類型

​交易事件

​入金事件

​元件專屬事件

​設定 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）

​啟動 KYC（WIDGET_KYC_INITIATION）

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

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

​禮品卡購買（WIDGET_PURCHASE_GIFT_CARD）

​最佳實務

​疑難排解

​需要協助？

運作方式

依應用程式類型的 Webhooks

私人應用 — 你的自有帳戶

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

元件應用（Widget apps）

事件類型

交易事件

入金事件

元件專屬事件

設定 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`）

啟動 KYC（`WIDGET_KYC_INITIATION`）

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

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

禮品卡購買（`WIDGET_PURCHASE_GIFT_CARD`）

最佳實務

疑難排解

需要協助？