Webhooks（网络钩子）

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

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

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

工作原理

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

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

按应用类型划分的 Webhooks

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

私有应用 — 你的自有账户

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

公共应用（OAuth）— 代表用户操作

Webhooks 针对已授权你的应用的账户活动触发。当用户通过 OAuth 授予你的应用访问权限时，他们的事件会路由到你注册的 webhooks——前提是该用户的 OAuth 授权包含所需的 scopes。无论用户通过你的直连 API 集成还是嵌入式小部件交互，此机制均适用；关键在于用户与应用之间存在 OAuth 关系。 常见用例： 知晓用户已将其账户与应用关联（或重新关联）；监控已连接账户的虚拟卡支出；实时拒付通知；跟踪存款完成；接收 KYC 状态更新。

小部件应用

小部件应用是特殊的公共应用。事件路由方式相同（基于 OAuth 关系），并且小部件应用还支持特定于小部件的事件，例如转账完成与礼品卡购买。

事件类型

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

OAUTH_USER_LINKED 仅投递给公共/OAuth 应用类型——私有应用的订阅者不会接收。由于它没有 scope 要求，你会接收每位用户与应用关联或重新关联的事件，无论其授予了哪些 scopes。使用它来配置或更新你本地的已连接用户记录，捕获授予的 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”视为“应用 → 客户”。

设置 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 key 对原始 JSON body 进行签名的 HMAC-SHA256 摘要。
`X-Event-ID`	此事件的唯一 UUID——用于去重。

请求体是一个 JSON 对象，每个负载都包含一个标识事件的 eventType 字段。

端点要求

仅限 HTTPS — 纯 HTTP 端点会在注册时被拒绝。
可公共访问，并能够接收 POST 请求。
在 30 秒内以 2xx 响应。 非 2xx 或超时将触发重试。
验证每次请求的 HMAC 签名。

验证签名

每次投递都包含 X-HMAC-Signature 请求头——这是以你应用的 API key 对原始 JSON body 进行 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	放弃投递；不再重试。

一旦你的端点恢复，新的事件会自动恢复投递。若需重新发送已耗尽重试次数的事件，请联系支持并提供相关的 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 之一。被拒绝的交易的 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
}

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。
`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"
}

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

需要帮助？

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

​工作原理

​按应用类型划分的 Webhooks

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

​公共应用（OAuth）— 代表用户操作

​小部件应用

​事件类型

​交易事件

​存款事件

​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）— 代表用户操作

小部件应用

事件类型

交易事件

存款事件

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

最佳实践

故障排除

需要帮助？