简体中文

English

简体中文

English

Appearance

使用 Webhook 来获取更新 ​

为什么要使用 Webhook ​

当您使用 BasicEx 构建集成时，您能希望您的服务接收来自 BasicEx 发生的事件，以便您的系统可以执行相应的操作，例如当您使用币趣支付时，想要在票据支付完成后进行相应的操作。

要在 BasicEx 中启用 Webhook 事件，您可以参考特定的 BasicEx 提供的服务来传入 Webhook 通知地址，例如在创建支付票据或构建代付请求时传入 Webhook 通知地址。根据您使用的特定服务，BasicEx 可以将实时事件数据推送到您服务的 Webhook 端点。BasicEx 通过使用 HTTPS 将 Webhook 事件作为 EVENT 对象的 JSON 负载发送到您的服务中。

Webhook 事件 ​

BasicEx 会根据特定的情况生成事件数据，并发送这些数据，以通知特定活动。

当事件发生后，BasicEx 会生成一个新的 Event 对象，单个 API 请求可能会导致创建多个事件。例如，如果您创建了支付票据，根据特定的选项，您可能将收到: invoice.paid, invoice.completed, invoice.expired事件。

通过在 BasicEx 中注册 Webhook 端点，您可以使 BasicEx 自动将事件对象作为 POST 请求的一部分发送到您服务的已注册 Webhook 端点。在您的 Webhook 端点收到事件后，您的服务可以进行相对应的操作

WARNING

收到 Webhook 通知后需要一个正文为空的 HTTP 200 响应，任何其他 HTTP 响应均视为发送失败。
币趣支付 服务器会多次尝试发送 Webhook 推送，直到发送成功或 币趣支付 服务器放弃。

Event Object ​

我们发送给您的 Webhook 端点的事件对象如下所示:

json
{
  "id": "500e8384-61b1-4219-855d-2a196330af52",
  "object": "event",
  "objectId": "40620230325105039975309362381014",
  "created": 1680064028243,
  "type": "invoice.completed",
  "data": {
    ......
  },
  "retriesNum": 0
}

Event Object 结构 ​

字段名称类型描述
idstring事件 ID，每一个 Webhook 事件的事件 ID 唯一
objectIdstringWebhook 承载事件详情 ID
objectstringWebhook 时间类型，默认: event
createdlongWebhook 的创建时间戳(13 位)
typestringWebhook 的通知事件类型，参考: Event Type
dataobjectWebhook 事件的具体内容，根据事件类型而定
retriesNumint此 Webhook 事件的重试次数

Event Type ​

类型名称描述
invoice.paid支付票据已支付成功事件通知，该事件通知在支付票据支付成功后触发，但是并不代表该支付票据已经完成，以 invoice.completed 事件通知为准
invoice.completed支付票据已完成事件通知，该事件通知在支付票据完成后触发，代表该支付票据已经完成
invoice.expired支付票据已过期事件通知，该事件通知在支付票据过期后触发，代表该支付票据已经过期
payout.completed代付成功事件,该事件通知在代付成功过后触发,代表代付成功
payout.failed代付失败事件,该事件通知在代付失败过后触发,代表代付失败

Webhook 安全验签 ​

为了确保 Webhook 事件是从币趣支付发起，我们强烈建议您对接收到的 Webhook 事件进行验签以证明是从币趣支付发出。币趣支付使用平台证书对 Webhook 数据进行签名，并将签名的数据放置在Header头: X-Webhook-Signature 中，同时会将签名该 Webhook 的平台证书序列号放置在Header头: X-Webhook-Signature-Serial中。

要获取平台证书，请查看下方: 获取平台证书信息 接口获取目前的币趣支付 平台证书列表。并通过 Header 中X-Webhook-Signature-Serial字段来获取最终进行签名的平台证书。

对于开发者而言，您需要在收到 Webhook 事件以后，对该 Webhook 事件进行安全验签，具体流程如下:

  1. 获取Header头中的X-Webhook-Signature-Serial，并获取平台证书列表获取指定证书序列号的证书信息

  2. 按照和币趣相同的签名方式，即将: Webhook 通知回调地址 + 原始数据流(币趣发送的 Webhook 事件数据)进行拼接，得到待签名数据体，例如:

    1. Webhook 通知回调地址(此处对应创建订单时传入的notificationUrl): https://***.com/webhook

    2. Webhook 事件内容:

      text
      {"id":"3a05d299-6a9d-44fb-90cb-f99347e2c0e6","objectId":"40820230831140740900502704128298","object":"event","created":"1693462063164","type":"payout.success","data":{"orderNo":"40820230831140740900502704128298","merOrderNo":"DAWWEQEQWRRFFF","currency":"USDT","totalAmount":"100.000000","tradeStartTime":"1693490860","chainPaymentInfo":null,"message":"","status":"completed"},"retriesNum":0}

    3. 则将其拼接的待签名数据体范例为(此处对应创建订单时传入的notificationUrl):

      text
      https://www.***.com/webhook{"id":"3a05d299-6a9d-44fb-90cb-f99347e2c0e6","objectId":"40820230831140740900502704128298","object":"event","created":"1693462063164","type":"payout.success","data":{"orderNo":"40820230831140740900502704128298","merOrderNo":"DAWWEQEQWRRFFF","currency":"USDT","totalAmount":"100.000000","tradeStartTime":"1693490860","chainPaymentInfo":null,"message":"","status":"completed"},"retriesNum":0}

  3. 你需要从平台证书中解析得到证书公钥信息以及证书的签名算法，并根据您的开发语言不同，调用不同的验签库，使用证书公钥，签名以及待签名数据体验证该 Webhook 是否由币趣发起。

你也可以参考我们的 BasicEx Java SDK 中关于Webhook验签部分的代码 来帮助理解Webhook的验签部分

获取平台证书 ​

提交地址：https://openapi.basicex.com/v2/platform/certificate

请求方式：GET

返回参数: ​

字段类型描述
certificatestring平台证书数据
serialNumberstring平台证书序列号

故障排除 ​

如果未按预期接收或处理 Webhook，请检查以下内容：

  • 验证您的 Webhook 处理程序 notificationURL 是否可以正确接收 POST。
  • 验证您的防火墙没有阻止来自它可能无法识别的服务器的 POST。
  • 可以通过发送 POST以及与指定票据关联的指令来重新发送 Webhook 。

Copyright © 2023-BasicEx