慧企星助 开放平台文档

慧企星助 开放平台面向企业三方系统提供标准 HTTP API,支持员工、绑定关系、项目、目标与目标复盘、任务、通知、便签、标签、贡献点和附件上传能力。 所有接口默认只作用于当前 API Key 所属企业,权限由后端统一控制并在请求时强校验。

显示全部接口

Webhook 事件通知

开放平台支持通过 Webhook 向三方应用主动推送任务、便签、贡献申请、工作汇报、奖章、成就、项目与福利相关事件通知。在 API Key 管理中配置回调地址和订阅的事件类型后,当相关业务发生变化时,开放平台会向订阅对应事件的全部企业集成 API Key 的回调地址异步发送 HTTP POST 请求,不限于发起操作的应用。

配置入口:企业管理后台 → 开放平台 → API Key 管理 → 编辑 API Key → 填写“三方事件回调地址”并选择需要订阅的事件类型。

事件类型

事件类型分类子分类触发时机
task.created任务类创建与发送任务创建成功(含草稿)。
task.sent任务类创建与发送任务发送。
task.awaitStart任务类创建与发送任务待开始。
task.received任务类执行流程任务接收。
task.refused任务类执行流程任务被拒收。
task.executing任务类执行流程任务执行中。
task.submitted任务类执行流程任务提交完成。
task.completed任务类执行流程任务已完成。
task.audited任务类审核与审批完成审核通过。
task.auditRejected任务类审核与审批完成审核不通过。
task.awaitingApproval任务类审核与审批待审批。
task.approved任务类审核与审批审批通过。
task.approvalRejected任务类审核与审批审批不通过。
task.changed任务类审核与审批任务变更待确认。
task.paused任务类挂起与暂停任务已暂停。
task.hangApply任务类挂起与暂停挂起申请。
task.hangFiringApply任务类挂起与暂停申请挂起启动。
task.suspended任务类挂起与暂停任务已挂起。
task.forwarding任务类转发与申诉转发中。
task.relayRefused任务类转发与申诉转发拒收。
task.relayAwaitingApproval任务类转发与申诉转发任务待审批。
task.relayApprovalRejected任务类转发与申诉转发任务审批不通过。
task.rejected任务类特殊流程完成任务被申诉。
task.canceled任务类特殊流程任务撤销申请。
task.deleted任务类删除任务删除。
note.created便签类便签通过开放平台创建便签成功。
note.updated便签类便签便签内容、权限、关注状态或所属关系更新成功。
note.deleted便签类便签便签删除成功。
note.shared便签类便签便签共享操作完成。
note.shareCanceled便签类便签便签取消共享操作完成。
note.sent便签类便签便签发送给负责人或参与人完成。
note.attachmentUploaded便签类便签便签附件上传成功。
notePackage.created便签类便签包通过开放平台创建便签包成功。
notePackage.updated便签类便签包便签包内容、权限、关注状态或所属关系更新成功。
notePackage.deleted便签类便签包便签包删除成功。
notePackage.shared便签类便签包便签包共享操作完成。
notePackage.shareCanceled便签类便签包便签包取消共享操作完成。
noteFolder.created便签类便签夹通过开放平台创建便签夹成功。
noteFolder.updated便签类便签夹便签夹名称、位置或关注状态更新成功。
noteFolder.deleted便签类便签夹便签夹删除成功。
scoreApply.created贡献类-贡献申请创建成功。
scoreApply.approved贡献类-贡献申请审批通过。
scoreApply.rejected贡献类-贡献申请审批不通过。
scoreApply.complained贡献类-贡献申请被申诉。
scoreApply.confirmed贡献类-贡献申请被确认。
report.sent汇报类-工作汇报提交发送成功。
report.confirmed汇报类-工作汇报被接收人确认。
report.appealed汇报类-对工作汇报考核结果提交申诉。
report.rejectAppealRejected汇报类-工作汇报的驳回申诉未通过。
report.assessed汇报类-工作汇报完成考核评分。
report.canceled汇报类-工作汇报撤回成功。
medal.published奖章类-通过开放平台颁发奖章成功。
medal.received奖章类-奖章被领取成功。
achievement.published成就类-通过开放平台颁发成就成功。
achievement.received成就类-成就被领取成功。
project.created项目类-通过开放平台创建项目成功。
project.updated项目类-通过开放平台修改项目成功。
project.deleted项目类-通过开放平台删除项目成功。
welfare.applied福利类-福利申请提交成功。
welfare.approved福利类-福利申请审批通过。
welfare.rejected福利类-福利申请审批驳回。
automationTask.created自动化任务类-通过开放平台创建自动化任务成功。
automationTask.passed自动化任务类-自动化任务审批通过。
automationTask.rejected自动化任务类-自动化任务审批不通过。
automationTask.sent自动化任务类-通过开放平台强制发送自动化任务成功。
automationTask.sendFailed自动化任务类-通过开放平台强制发送自动化任务失败。
rewardTask.created悬赏任务类-通过开放平台创建悬赏任务成功。
rewardTask.received悬赏任务类-员工领取悬赏任务成功。
projectTask.created项目任务类-通过开放平台创建项目任务成功。
projectTask.passed项目任务类-项目任务审批通过。
projectTask.sent项目任务类-项目任务发送成功(发送后以同一任务 Id 落地为正式任务)。
common.accountUnbound通用类-三方账号解绑。
任务类事件范围:任务类事件仅在任务由开放平台来源的操作产生变化时触发(如通过某个 API Key 创建的任务),但会推送给订阅对应事件的全部企业集成 API Key,不限于发起操作的 Key。
贡献类事件范围:贡献类事件仅在贡献申请由开放平台来源的操作产生变化时触发(如通过某个 API Key 提交的申请),但会推送给订阅对应事件的全部企业集成 API Key,不限于发起操作的 Key。
便签类事件范围:便签类事件仅在便签、便签包或便签夹操作由开放平台来源发起并成功关联时触发,但会推送给订阅对应事件的全部企业集成 API Key,不限于发起操作的 Key。事件数据只返回业务 Id(noteIdpackageIdfolderId),不返回员工真实 Guid;员工身份仍以接口约定的 virtualId 传递。
汇报 / 奖章 / 成就 / 福利类事件范围:这四类事件仅在异步写操作由开放平台来源发起时触发,且仅在该操作对应的队列任务处理成功后推送;队列失败不推送事件。事件会推送给订阅对应事件的全部企业集成 API Key,不限于发起操作的 Key。同步动作(如汇报确认、申诉、驳回申诉、项目增删改)在接口返回成功时即推送。
自动化任务 / 悬赏任务类事件范围:这两类事件仅在操作通过开放平台发起并被成功记录来源 API Key 时触发。事件载荷只返回业务 Id(taskId),不返回员工真实 Guid;员工身份仍以接口约定的 virtualId 传递。由定时作业自动触发、无法确定来源 API Key 的操作不推送事件。事件会推送给订阅对应事件的全部企业集成 API Key,不限于发起操作的 Key。
项目任务类事件范围:项目任务类事件仅在操作通过开放平台发起并被成功记录来源 API Key 时触发。事件载荷只返回业务 Id(taskId),不返回员工真实 Guid。事件会推送给订阅对应事件的全部企业集成 API Key,不限于发起操作的 Key。项目任务发送后会以同一任务 Id 落地为正式任务,因此 projectTask.sent 之后如需继续操作,应改用任务接口。目前项目任务暂未提供「审批不通过」的对外接口,因此不存在对应的不通过事件。
凭据用途限制:只有企业集成用途的 API Key 才会收到事件回调。个人 MCP 凭据面向单个成员的个人智能体场景,不承载企业级事件订阅,即使其记录上配置了回调地址也不会收到任何事件。

查询支持的事件类型

三方应用可以通过接口动态获取开放平台支持的全部事件类型,用于构建事件订阅 UI 或验证配置:

GET /api/openplatform/tasks/webhook-event-types

权限要求:需要有效的 API Key 鉴权(X-API-Key、X-Timestamp、X-Nonce、X-Signature)。

请求示例

GET /api/openplatform/tasks/webhook-event-types HTTP/1.1
Host: your-openplatform-domain.com
X-API-Key: your-api-key-here
X-Timestamp: 1718620800
X-Nonce: abc123def456
X-Signature: hmac-sha256-signature-here

响应示例

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": [
    {
      "value": "task.created",
      "label": "任务创建",
      "description": "通过开放平台 API 创建任务时触发。",
      "category": "task"
    },
    {
      "value": "task.sent",
      "label": "任务下发",
      "description": "任务下发给执行人时触发。",
      "category": "task"
    },
    {
      "value": "task.received",
      "label": "任务接收",
      "description": "执行人接收任务时触发。",
      "category": "task"
    },
    {
      "value": "task.executing",
      "label": "任务开始执行",
      "description": "执行人开始执行任务时触发。",
      "category": "task"
    },
    {
      "value": "task.paused",
      "label": "任务暂停",
      "description": "任务被暂停时触发。",
      "category": "task"
    },
    {
      "value": "task.suspended",
      "label": "任务挂起",
      "description": "任务被挂起时触发。",
      "category": "task"
    },
    {
      "value": "task.deleted",
      "label": "任务删除",
      "description": "任务被删除时触发。",
      "category": "task"
    },
    {
      "value": "task.submitted",
      "label": "任务提交",
      "description": "执行人完成任务并提交时触发。",
      "category": "task"
    },
    {
      "value": "task.approved",
      "label": "任务审核通过",
      "description": "任务审核人通过任务时触发。",
      "category": "task"
    },
    {
      "value": "task.rejected",
      "label": "任务审核不通过",
      "description": "任务审核人不通过任务时触发。",
      "category": "task"
    },
    {
      "value": "scoreApply.created",
      "label": "贡献申请创建成功",
      "description": "通过开放平台提交贡献申请成功后触发。",
      "category": "score"
    },
    {
      "value": "scoreApply.approved",
      "label": "贡献申请审批通过",
      "description": "贡献申请审批通过时触发。",
      "category": "score"
    },
    {
      "value": "scoreApply.rejected",
      "label": "贡献申请审批不通过",
      "description": "贡献申请审批不通过时触发。",
      "category": "score"
    },
    {
      "value": "scoreApply.complained",
      "label": "贡献申请申诉",
      "description": "贡献申请被申诉时触发。",
      "category": "score"
    },
    {
      "value": "scoreApply.confirmed",
      "label": "贡献申请确认",
      "description": "贡献申请被确认时触发。",
      "category": "score"
    },
    {
      "value": "report.sent",
      "label": "汇报发送",
      "description": "工作汇报提交发送成功后触发。",
      "category": "report"
    },
    {
      "value": "medal.published",
      "label": "奖章颁发",
      "description": "通过开放平台颁发奖章成功后触发。",
      "category": "medal"
    },
    {
      "value": "achievement.received",
      "label": "成就领取",
      "description": "成就被领取成功后触发。",
      "category": "achievement"
    },
    {
      "value": "project.created",
      "label": "项目创建",
      "description": "通过开放平台创建项目成功后触发。",
      "category": "project"
    },
    {
      "value": "welfare.approved",
      "label": "福利审批通过",
      "description": "福利申请审批通过时触发。",
      "category": "welfare"
    },
    {
      "value": "automationTask.created",
      "label": "自动化任务创建成功",
      "description": "通过开放平台创建自动化任务成功后触发。",
      "category": "automationTask"
    },
    {
      "value": "automationTask.sent",
      "label": "自动化任务发送成功",
      "description": "通过开放平台强制发送自动化任务成功时触发。",
      "category": "automationTask"
    },
    {
      "value": "rewardTask.created",
      "label": "悬赏任务创建成功",
      "description": "通过开放平台创建悬赏任务成功后触发。",
      "category": "rewardTask"
    },
    {
      "value": "rewardTask.received",
      "label": "悬赏任务领取成功",
      "description": "员工领取悬赏任务成功后触发。",
      "category": "rewardTask"
    },
    {
      "value": "projectTask.created",
      "label": "项目任务创建成功",
      "description": "通过开放平台创建项目任务成功后触发。",
      "category": "projectTask"
    },
    {
      "value": "projectTask.passed",
      "label": "项目任务审批通过",
      "description": "项目任务审批通过后触发。",
      "category": "projectTask"
    },
    {
      "value": "projectTask.sent",
      "label": "项目任务发送成功",
      "description": "项目任务发送成功后触发,任务落地为正式任务。",
      "category": "projectTask"
    },
    {
      "value": "common.accountUnbound",
      "label": "账号解绑",
      "description": "三方账号与员工解绑时触发。",
      "category": "common"
    }
  ]
}

响应字段说明

字段类型说明
statusCodeint状态码,100 表示成功。
msgstring响应消息。
dataarray事件类型列表。
data[].valuestring事件类型标识符,用于订阅配置。
data[].labelstring事件类型的中文名称。
data[].descriptionstring事件触发时机的详细说明。
data[].categorystring事件分类:task(任务类)、note(便签类)、score(贡献类)、report(汇报类)、medal(奖章类)、achievement(成就类)、project(项目类)、welfare(福利类)、automationTask(自动化任务类)、rewardTask(悬赏任务类)、projectTask(项目任务类)或 common(通用类)。
使用场景:建议在 API Key 配置页面调用此接口,动态渲染事件类型多选框,避免硬编码事件列表。

事件 Data 字段详解

不同事件类型会在 data 字段中返回不同的业务数据,三方应用应根据 eventType 解析对应字段:

1. 任务类事件

task.created - 任务创建

字段类型说明
taskIdstring (UUID)任务唯一标识符。
namestring任务名称。
createdAtstring任务创建时间(ISO 8601 格式)。
{
  "eventType": "task.created",
  "timestamp": "1718620800",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "完成季度复盘",
    "createdAt": "2026-06-17T16:00:00"
  }
}

task.sent / task.received / task.executing / task.paused / task.suspended / task.deleted / task.submitted / task.approved / task.rejected - 任务状态变更

字段类型说明
taskIdstring (UUID)任务唯一标识符。
eventTypestring事件类型标识,与外层 eventType 一致。
建议操作:接收到任务状态变更事件后,三方可调用 GET /api/openplatform/tasks/{taskId} 接口获取任务完整详情(包括状态、执行人、进度、附件等)。
{
  "eventType": "task.submitted",
  "timestamp": "1718624400",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "task.submitted"
  }
}

2. 便签类事件

note.created / note.updated / note.deleted / note.shared / note.shareCanceled / note.sent / note.attachmentUploaded - 便签状态变更

notePackage.created / notePackage.updated / notePackage.deleted / notePackage.shared / notePackage.shareCanceled - 便签包状态变更

noteFolder.created / noteFolder.updated / noteFolder.deleted - 便签夹状态变更

字段类型说明
noteIdstring (UUID)便签业务 Id。便签类事件返回。
packageIdstring (UUID)便签包业务 Id。便签包类事件返回。
folderIdstring (UUID)便签夹业务 Id。便签夹类事件返回。
建议操作:接收到便签事件后,三方可根据事件类型调用便签或便签包详情接口获取最新数据。便签 Webhook 只表示对应业务操作已经成功完成,不保证回调到达顺序。
{
  "eventType": "note.updated",
  "timestamp": "1718635200",
  "data": {
    "noteId": "d4e5f6a7-b8c9-0123-defa-456789012345"
  }
}

3. 贡献类事件

scoreApply.created - 贡献申请创建

字段类型说明
applyIdstring (UUID)贡献申请唯一标识符。
applyTypeint申请类型数值:0 行为标准申请、1 自定义申请(与贡献申请详情响应的 applicationType 同口径)。
scoredecimal申请贡献点数量。
isAnonymousbool是否匿名申请。
createdAtstring申请创建时间(ISO 8601 格式)。
{
  "eventType": "scoreApply.created",
  "timestamp": "1718628000",
  "data": {
    "applyId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "applyType": 1,
    "score": 5.0,
    "isAnonymous": false,
    "createdAt": "2026-06-17T17:00:00"
  }
}

scoreApply.approved / scoreApply.rejected / scoreApply.confirmed / scoreApply.complained - 贡献申请状态变更

字段类型说明
applyIdstring (UUID)贡献申请唯一标识符。
statusCodeint业务状态码(100 表示成功)。
msgstring状态变更说明信息(如审批意见)。
建议操作:接收到贡献申请状态变更事件后,三方可调用贡献申请详情接口获取完整信息(包括审批人、审批时间、贡献点变更记录等)。
{
  "eventType": "scoreApply.approved",
  "timestamp": "1718631600",
  "data": {
    "applyId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "statusCode": 100,
    "msg": "审批通过"
  }
}
说明:scoreApply.rejectedscoreApply.confirmedscoreApply.complaineddata 字段结构与上例一致,均返回 applyIdstatusCodemsg

4. 工作汇报类事件

report.sent / report.confirmed / report.appealed / report.rejectAppealRejected / report.assessed / report.canceled - 工作汇报状态变更

字段类型说明
reportIdstring (UUID)工作汇报业务 Id,可直接用于查询汇报详情。
statusCodeint业务状态码(100 表示成功)。
msgstring业务结论说明,来自领域层的真实处理结果。
建议操作:接收到汇报状态变更事件后,三方可调用 GET /api/openplatform/reports/{reportId} 获取汇报完整详情。发送、撤回、考核评分的 reportId 取自队列载荷;个别事件在载荷缺少可用 Id 时 reportId 为零值 Guid,此时请以自身记录的关联关系为准。
{
  "eventType": "report.sent",
  "timestamp": "1718635200",
  "data": {
    "reportId": "5f1c2a3b-4d5e-4f60-8a71-9b2c3d4e5f60",
    "statusCode": 100,
    "msg": "发送成功"
  }
}

5. 奖章与成就类事件

medal.published / medal.received / achievement.published / achievement.received - 奖章与成就颁发、领取

字段类型说明
idstring (UUID)奖章或成就的业务 Id,与对应接口返回的 id 同口径。
statusCodeint业务状态码(100 表示成功)。
msgstring业务结论说明。
建议操作:奖章与成对的领取动作通过 medalIdachievementId 关联到具体记录,事件载荷统一回填为 id;三方可据此调用 GET /api/openplatform/medals/{id}GET /api/openplatform/achievements/{id} 获取最新数据。
{
  "eventType": "medal.received",
  "timestamp": "1718638800",
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "statusCode": 100,
    "msg": "领取成功"
  }
}

6. 项目与福利类事件

project.created / project.updated / project.deleted - 项目增删改(同步动作,接口返回成功即推送)

字段类型说明
projectIdstring (UUID)项目业务 Id,可直接用于查询项目详情。
msgstring业务结论说明。

welfare.applied / welfare.approved / welfare.rejected - 福利申请与审批(异步动作,队列处理成功后推送)

字段类型说明
applyIdstring (UUID)福利申请记录 Id。
statusCodeint业务状态码(100 表示成功)。
msgstring业务结论说明。福利申请被驳回时同样返回 100,表示“驳回动作执行成功”,业务语义请以 eventType 为准。
{
  "eventType": "welfare.approved",
  "timestamp": "1718642400",
  "data": {
    "applyId": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "statusCode": 100,
    "msg": "审批通过"
  }
}

7. 自动化任务与悬赏任务类事件

automationTask.created - 自动化任务创建成功(同步动作,接口返回成功即推送)

字段类型说明
taskIdstring (UUID)自动化任务业务 Id,可直接用于查询任务详情。
statusCodeint业务状态码(100 表示成功)。
msgstring业务结论说明。

automationTask.passed / automationTask.rejected - 自动化任务审批(异步动作,队列处理成功后推送)

automationTask.sent / automationTask.sendFailed - 自动化任务发送结果(同步动作,强制发送接口返回后推送)

字段类型说明
taskIdstring (UUID)自动化任务业务 Id。
statusCodeint业务状态码(100 表示成功)。审批不通过、发送失败时返回对应失败码。
msgstring业务结论说明。审批不通过与发送失败均以事件类型区分语义,请以 eventType 为准。
{
  "eventType": "automationTask.passed",
  "timestamp": "1718646000",
  "data": {
    "taskId": "f6a7b8c9-d0e1-2345-fabc-678901234567",
    "statusCode": 100,
    "msg": "审批成功!"
  }
}
说明:定时作业自动触发的任务发送不携带来源 API Key,因此不会推送发送类事件;只有通过开放平台强制发送接口触发的发送才会推送 automationTask.sentautomationTask.sendFailed

rewardTask.created - 悬赏任务创建成功(同步动作,接口返回成功即推送)

字段类型说明
taskIdstring (UUID)悬赏任务业务 Id,可直接用于查询任务详情。
statusCodeint业务状态码(100 表示成功)。
msgstring业务结论说明。

rewardTask.received - 悬赏任务领取成功(异步动作,队列处理成功后推送)

字段类型说明
taskIdstring (UUID)被领取的悬赏任务业务 Id。
statusCodeint业务状态码(100 表示成功)。
msgstring业务结论说明。
{
  "eventType": "rewardTask.received",
  "timestamp": "1718649600",
  "data": {
    "taskId": "a7b8c9d0-e1f2-3456-abcd-789012345678",
    "statusCode": 100,
    "msg": "领取成功!"
  }
}

8. 项目任务类事件

projectTask.created - 项目任务创建成功(同步动作,接口返回成功即推送)

字段类型说明
taskIdstring (UUID)项目任务业务 Id,可直接用于查询任务详情。
statusCodeint业务状态码(100 表示成功)。
msgstring业务结论说明。

projectTask.passed / projectTask.sent - 项目任务审批通过、发送成功(异步动作,队列处理成功后推送)

字段类型说明
taskIdstring (UUID)项目任务业务 Id。发送成功后该 Id 同时是正式任务 Id。
statusCodeint业务状态码(100 表示成功)。
msgstring业务结论说明。
{
  "eventType": "projectTask.sent",
  "timestamp": "1718653200",
  "data": {
    "taskId": "b8c9d0e1-f2a3-4567-bcde-890123456789",
    "statusCode": 100,
    "msg": "发送成功"
  }
}
说明:项目任务发送后会以同一任务 Id 落地为正式任务,后续请改用任务接口继续操作。项目任务暂未提供「审批不通过」的对外接口,因此不会推送对应的不通过事件。

9. 通用类事件

common.accountUnbound - 三方账号解绑

字段类型说明
apiKeyIdstring (UUID)API Key 唯一标识符。
thirdPartyUserIdstring三方系统的用户唯一标识。
employeeVirtualIdstring慧企星助平台员工虚拟 ID(解绑后该员工将无法再通过三方身份访问)。
eventTypestring事件类型标识,固定为 "common.accountUnbound"
处理建议:接收到解绑事件后,三方应用应:
  • 立即失效该 thirdPartyUserId 对应的访问令牌或会话。
  • 清除三方系统中与该员工相关的缓存数据。
  • 如三方系统需要,可记录解绑时间用于审计。
  • 该员工下次尝试通过三方登录时,应引导其重新授权绑定。
{
  "eventType": "common.accountUnbound",
  "timestamp": "1718635200",
  "data": {
    "apiKeyId": "c3d4e5f6-a7b8-9012-cdef-a12345678901",
    "thirdPartyUserId": "third_party_user_12345",
    "employeeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
    "eventType": "common.accountUnbound"
  }
}

回调请求格式

开放平台会以 HTTP POST 方式向配置的回调地址发送 JSON 数据:

参数类型说明
eventTypestring事件类型,如 task.created
timestampstringWebhook 发送时的 Unix 秒级时间戳字符串,例如 "1718620800";该值同时用于签名验证与防重放校验。
dataobject事件详细数据(由具体事件类型决定,见上方"事件 Data 字段详解")。

签名验证

每个 Webhook 请求都会在 HTTP Header 中携带签名,三方应用应验证签名以确保请求来源可信:

Header 名称说明
X-Webhook-SignatureHMAC-SHA256 签名值(十六进制字符串)。
X-Webhook-Timestamp与请求体中的 timestamp 一致,值为 Unix 秒级时间戳字符串。

签名算法:

signature = HMAC-SHA256(
  key = webhookSecret,
  message = timestamp + "\n" + requestBodyJson
)
验签规则:
  • 签名原文只包含 timestamp、换行符 \n 和完整请求体 JSON,不拼接 eventType、URL 或其他 Header。
  • 验签时必须使用接收到的原始请求体字符串,不能先反序列化再重新序列化,否则字段顺序、空格或转义差异会导致签名不一致。
  • 建议按 UTC 校验时间戳有效期,例如与 DateTime.UtcNow 比较,并控制在 5 分钟误差窗口内。
安全提示:webhookSecret 由后端在配置 Webhook 回调地址时自动生成(256 位随机字符串,使用 RNGCryptoServiceProvider 密码学安全随机数生成器),用户可随时点击"重新生成密钥"按钮重新生成。密钥仅在配置成功时返回给前端展示,不会在网络传输中暴露。接收到 Webhook 请求后,务必先验证签名,再处理业务逻辑。

重试机制

事件会向每个订阅该事件的 API Key 独立投递、独立记录投递日志,任一 Key 的投递失败不影响其他 Key。开放平台会对单个 Key 的 Webhook 投递失败进行自动重试,最多重试 3 次:

  • 第 1 次重试:失败后 1 分钟
  • 第 2 次重试:失败后 5 分钟
  • 第 3 次重试:失败后 30 分钟

如果某个 Key 的 3 次重试后仍然失败,该事件对该 Key 标记为投递失败,可在日志中查看详细信息。

最佳实践:三方应用接收到 Webhook 请求后,应尽快返回成功结果,复杂业务逻辑请异步处理,避免超时导致重试。若已接收成功,建议返回 HTTP 200 且响应体 {"statusCode":100,"msg":"success"};若验签失败、参数非法或业务未接收成功,应返回非成功 HTTP 状态码,或在响应体中返回非 100statusCode,开放平台会按失败处理并进入重试。