Webhook 配置

事件回调地址配置、签名校验、投递记录与重试策略

接口总览 快速入门 套餐与订单 API Key 管理 Webhook 配置 SMS 映射 错误码表

概述

Webhook 用于接收平台主动推送的事件通知。当开票任务完成、红字冲红成功等事件发生时，平台会向您配置的回调 URL 发送 POST 请求，无需轮询查询任务状态。

配置入口：控制台 → Webhook & SMS → Webhook 回调 Tab。

可订阅事件

事件类型触发时机说明
invoice.completed蓝字开票成功发票开具完成，可下载发票文件
invoice.failed蓝字开票失败开票任务执行失败，包含错误信息
red_invoice.completed红字冲红成功红字发票冲红完成
task.updated任务状态变更任意任务状态变化时触发（通用事件）

创建 Webhook

在控制台 → Webhook & SMS 页面，点击"创建 Webhook"按钮：

1. 填写回调 URL（生产环境必须为 HTTPS）

2. 勾选需要订阅的事件类型（至少一个）

3. 创建成功后，系统生成签名密钥（Secret），仅展示一次，请立即复制保存

Secret 仅在创建时展示一次，之后无法再次查看。请妥善保存，用于后续验签。

回调请求格式

平台向您的回调 URL 发送 POST 请求，Content-Type 为 application/json。

请求头包含以下字段：

请求头说明
X-SignatureHMAC-SHA256 签名，格式 sha256=xxxx
X-Event-Type事件类型（如 invoice.completed）
X-Delivery-Id投递唯一 ID，用于幂等去重
X-Timestamp投递时间戳（Unix 秒）

请求体示例：

{
  "event_type": "invoice.completed",
  "timestamp": "2026-09-12T10:30:00.000Z",
  "data": {
    "task_id": "task-abc123",
    "invoice_number": "24442000000012345678",
    "amount": 100.00
  }
}

签名校验

使用创建 Webhook 时获得的 Secret 对请求体进行 HMAC-SHA256 签名校验，确保请求来自平台：

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
建议始终校验签名，防止伪造请求。比较签名时使用恒定时间比较（timingSafeEqual）防止时序攻击。

响应要求

您的服务器需在 10 秒内返回 HTTP 2xx 状态码表示接收成功。超时或非 2xx 响应视为投递失败，平台会自动重试。

投递记录与重试

每个 Webhook 的投递记录可在控制台查看：点击 Webhook 卡片上的"投递记录"按钮。

投递状态：

状态说明
succeeded投递成功（HTTP 2xx）
failed投递失败（超时、非 2xx、连接错误）

投递失败时平台会自动重试，每次投递记录会显示重试次数和最后一次 HTTP 状态码。

测试发送

在 Webhook 列表中点击"测试发送"按钮，平台会向您的回调 URL 发送一个 event_type: "test" 的测试事件，用于验证连通性。

测试事件请求体：

{
  "event_type": "test",
  "timestamp": "2026-09-12T10:30:00.000Z",
  "data": {
    "webhook_id": 1,
    "message": "测试投递"
  }
}

更新 Webhook

可修改回调 URL 和订阅事件列表。修改后立即生效，不影响已创建的投递记录。

← 返回接口总览