书写 Webhooks

概述

书写 webhooks 允许您实时接收有关商业票据发行流程中状态变更和重要事件的通知。当事件发生时，QI Tech 会自动向您系统中配置的 URL 发送 HTTP POST 载荷。

Webhooks 配置

要接收 webhooks，您需要在系统中配置端点 URL。请参阅 webhooks 配置文档了解如何注册和管理您的 webhook URL 的更多详情。

认证和安全

QI Tech 发送的所有 webhooks 在 SIGNATURE header 中携带一个 JWT，使用与合作伙伴共享的 Signature Key 以 HS256 签名。请求体不会被直接签名，而是通过 payload_md5 claim 进入该 token。您的系统必须验证此签名，以确保接收数据的真实性和完整性。验证步骤请参阅 webhooks 认证文档。

可用事件

发行人管理

发行人登记已批准

当发行人的登记被合规团队批准时发送。

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

发行人登记未批准

当发行人的登记被合规团队拒绝时发送。

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}

发行人自动签署 — 状态变更

在加入协议的签署信封被开启时以及该信封办结时发送。信封在启用申请调用过程中即被开启，该调用已直接以 pending_signature 响应 — 对于发起调用的一方，此 webhook 只是确认响应中已返回的内容；对于该 tenant 下的其他消费方，它则是加入协议已可供签署的通知。启用由集成方通过 POST .../auto_signature 申请。各状态的含义请参阅自动签署流程。

该事件在三个时点触发：pending_signature、enabled 和 reproved。自动签署的创建（pending_term_generation）与取消（canceled）不会产生 webhook — 创建体现在申请本身的响应中，取消则通过自动签署查询观察。

Event Type: issuer_management.auto_signature_status_change

Payload:

{
  "event_type": "issuer_management.auto_signature_status_change",
  "event_datetime": "2026-02-10T09:16:03Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
    "status": "pending_signature"
  }
}

字段	类型	描述
`issuer_key`	string	发行人的唯一键。
`issuer_auto_signature_key`	string	自动签署的唯一键。
`status`	string	当前状态。在 webhook 中始终为 `pending_signature`、`enabled` 或 `reproved`。

收到各状态时的处理方式：

收到的状态	处理方式
`pending_signature`	查询签署链接，并引导发行人的每一位签署人访问其专属链接。
`enabled`	发行人已启用自动签署：此后的发行将自动签署。
`reproved`	加入协议的信封被拒签、取消或已过期。在重新创建启用之前，发行将走人工签署流程。

清算账户管理

清算账户申请状态变更

当发行人的清算账户开户申请状态发生变化时发送。event_data.status 字段说明发生了哪种变化，在做任何处理之前都必须先判断该字段，因为同一个 event_type 同时承载拒绝和开立两种情况。

`status`	含义
`rejected`	BaaS 拒绝了开户，例如因为 Bacen Protege+ 的限制。账户不会被开立，在新的申请获得通过之前，该发行人的清算会被阻断。与发行人解决原因之后，请使用开户重试。
`approved`	申请已通过 BaaS 的校验。此时账户尚不存在：它会在该发行人的第一笔操作发行时开立。
`opened`	账户已开立，可以接收清算。

approved 事件在发行人登记后几分钟内到达，是 rejected 的对应事件。通过它即可得知账户能够开立，无需等待第一次发行。

Event Type: liquidation_account.account_request_status_change

拒绝的 Payload：

{
  "event_type": "liquidation_account.account_request_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "account_request_key": "7e1c53d6-d372-4020-be6b-ed94248d7ae9",
    "status": "rejected",
    "rejection_reason": "Rejeitado devido ao Bacen Protege+",
    "account_info": {
      "account_branch": "0001",
      "account_number": "1234567",
      "account_digit": "3"
    }
  }
}

在拒绝的情况下，account_info 字段是可选的，仅当 BaaS 返回被拒账户的数据时才会发送。rejection_reason 按 BaaS 返回的原文透传。

通过的 Payload：

{
  "event_type": "liquidation_account.account_request_status_change",
  "event_datetime": "2025-07-30T16:07:30Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "account_request_key": "7e1c53d6-d372-4020-be6b-ed94248d7ae9",
    "status": "approved",
    "account_info": {
      "account_branch": "0001",
      "account_number": "1234567",
      "account_digit": "3"
    }
  }
}

开立的 Payload：

{
  "event_type": "liquidation_account.account_request_status_change",
  "event_datetime": "2025-07-30T16:12:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "account_request_key": "7e1c53d6-d372-4020-be6b-ed94248d7ae9",
    "status": "opened",
    "account_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
    "account_info": {
      "account_branch": "0001",
      "account_number": "1234567",
      "account_digit": "3"
    }
  }
}

账户的当前状态也可以随时通过清算账户查询获取。

投资人管理

投资人登记已批准

当投资人的登记被合规团队批准时发送。

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

投资人登记未批准

当投资人的登记被合规团队拒绝时发送。

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}