Webhook（回调）

Webhook 让你的应用在 Fluz 平台发生事件时即时接收通知。无需轮询，你只需注册一个 HTTPS 端点，Fluz 就会在事件发生的那一刻将数据推送给你——例如虚拟卡交易、被拒购、存款完成、用户通过 OAuth 关联账户等。

本页涵盖所有 webhook 事件，跨越多个平台领域（交易活动、存款、组件流程以及 OAuth 账户关联），不隶属于单一功能。

Webhook 适用于 Fluz 平台的所有应用类型：在你自己账户上运行的私有应用、代表其他用户通过 API 行动的公共 OAuth 应用，以及嵌入式组件应用。

工作原理

在开发者门户为你的应用注册一个 webhook URL。
选择要监听的事件类型（或订阅全部事件）。
当匹配的事件发生时，Fluz 会向你的 URL 发送带签名的 JSON 负载的 HTTP POST 请求。
你的服务器验证签名，返回 2xx 确认，并处理该事件。

如果你的端点不可用或返回错误，Fluz 会在放弃该次投递前，采用指数退避重试最多5 次。

按应用类型区分的 Webhook

事件如何路由到你的应用取决于你的应用模型。

私有应用 — 你的自有账户

Webhook 针对你的自有账户的活动触发。任何你所拥有账户上的交易、拒付或存款，都会触发注册在你应用上的 webhook。 常见用例： 当虚拟卡交易被授权或结算时发送通知；实时拒付告警；监控存款与消费账户的余额变动。

公共应用（OAuth）— 代表用户行动

Webhook 针对已授权你的应用的账户活动触发。当用户通过 OAuth 授予你的应用访问权限时，只要该用户的 OAuth 授权包含所需的 scope，事件就会被路由到你注册的 webhook。不论用户是通过你直接的 API 集成还是通过嵌入式组件进行交互，只要用户与应用之间存在 OAuth 关系即可。 常见用例： 知道用户何时已将账户与应用关联（或重新关联）；监控已连接账户的虚拟卡消费；实时拒付通知；跟踪存款完成；接收 KYC 状态更新。组件应用是一种特殊的公共应用。事件的路由方式相同（基于 OAuth 关系），并且组件应用还支持组件特有的事件，例如转账完成与礼品卡购买。

事件类型

仅当你的应用——以及对于公共/OAuth 应用，具体用户的 OAuth 授权——拥有所需的 scope 时，Fluz 才会投递该事件。无所需 scope 的事件（例如 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 关联。首次关联与后续更新（如授予的 scope 发生变化）都会触发。	None

OAUTH_USER_LINKED 仅投递给公共/OAuth 应用类型——私有应用订阅者不会收到。由于它没有 scope 要求，你会对每个与应用建立或重新建立关联的用户收到该事件，无论他们授予了哪些 scope。用它来开通或更新你本地的已连接用户记录、捕获授予的 scope 集合，并通过 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” 理解为 “应用 → 顾客”。

设置 webhook

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。你的端点会立即开始接收事件。

管理 webhook

多个端点 — 你可以为每个应用注册多个 webhook URL。
变更订阅事件 — 删除该 webhook 并用新的事件选择重新创建。
移除 webhook — 点击其旁边的 Remove。该 webhook 会立刻被归档并停止接收事件。

接收 webhook

请求格式

每个 webhook 都以 HTTP POST 形式投递，并包含以下请求头：

Header	Description
`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（这会触发重试）。

重试策略

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。

幂等性与顺序

Webhook 可能会被多次投递，且不保证投递顺序。

使用 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 关联时触发——首次关联与后续更新（例如用户以不同的 scope 重新授权）都会触发。仅限公共/OAuth 与组件应用。接收该事件无需任何 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"
  ]
}

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[]	该用户授予的去重后的 scope 键（例如 `LIST_PAYMENT`、`MAKE_DEPOSIT`）。

由于 OAUTH_USER_LINKED 会在重新关联/更新时再次触发，请将其视为 upsert：首次收到时创建已连接用户，后续收到时刷新已存储的 scope 集合。

发起 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 key 对原始请求体验证 X-HMAC-Signature，再进行处理。
用事件 ID 去重。 追踪 X-Event-ID，以处理重试/重复投递。
将类枚举字段视为开放字符串。 新的 transactionType、channel 与 declineCategory 值可能陆续出现；只针对你关心的值分支，并容忍未知值。
对 OAUTH_USER_LINKED 执行 upsert。 它可能对同一用户触发多次；每次都刷新所存储的 scope 集合，而不是假设仅首次触发。
接受未知字段。 负载可能随时间新增字段；忽略未识别字段而不是失败。
监控你的端点。 对持续的非 2xx 响应发出告警——在 5 次失败后，该事件的投递会被放弃。

故障排查

Symptom	Likely cause	Fix
未收到任何 webhook	端点不可达或返回错误	确认 URL 正确、可通过 HTTPS 公网访问并返回 `2xx`。
缺失某些事件类型	应用缺少所需 scope	确保你的应用持有该事件列出的 scope。
公共应用未收到某用户的事件	用户未授权所需 scope	确认该用户的 OAuth 授权包含所需 scope。
未收到 `OAUTH_USER_LINKED`	在私有应用上订阅，或未订阅	此事件仅限公共/OAuth。请在 OAuth 或组件应用上订阅（或使用全量订阅）。
签名验证失败	使用了错误的 API key，或对重序列化的请求体进行验证	使用你应用的 API key，并基于原始请求体进行验证。
出现重复投递	超时后的重试	使用 `X-Event-ID` 实现幂等性。
事件停止到达	连续 5 次失败已耗尽重试	修复你的端点；新事件会自动恢复投递。联系支持以重放已耗尽重试的事件。

需要帮助？

技术问题： 检查你的端点日志，并连同 X-Event-ID 联系支持。
关于 scope 的问题： 参见 Application Scopes 与 Decline Codes。

​工作原理

​按应用类型区分的 Webhook

​私有应用 — 你的自有账户

​公共应用（OAuth）— 代表用户行动

​组件应用（Widget apps）

​事件类型

​交易事件

​存款事件

​OAuth 事件

​组件特有事件

​设置 webhook

​1. 打开开发者门户

​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 apps）

事件类型

交易事件

存款事件

OAuth 事件

组件特有事件

设置 webhook

1. 打开开发者门户

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

最佳实践

故障排查

需要帮助？