慧企星助开放平台文档

Webhook 事件通知

开放平台支持通过 Webhook 向三方应用主动推送任务、贡献申请和便签相关事件通知。在 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`	便签类	便签夹	便签夹删除成功。
`score_apply.created`	贡献类	-	贡献申请创建成功。
`score_apply.approved`	贡献类	-	贡献申请审批通过。
`score_apply.rejected`	贡献类	-	贡献申请审批不通过。
`score_apply.complained`	贡献类	-	贡献申请被申诉。
`score_apply.confirmed`	贡献类	-	贡献申请被确认。
`common.accountUnbound`	通用类	-	三方账号解绑。

任务类事件范围：任务类事件只会推送与当前 API Key 相关的任务（通过该 API Key 创建的任务）。

贡献类事件范围：贡献类事件只会推送与当前 API Key 相关的贡献申请（通过该 API Key 提交的申请）。

便签类事件范围：便签类事件只会推送通过当前 API Key 发起并成功关联的便签、便签包或便签夹操作。事件数据只返回业务 Id（noteId、packageId、folderId），不返回员工真实 Guid；员工身份仍以接口约定的 virtualId 传递。

查询支持的事件类型

三方应用可以通过接口动态获取开放平台支持的全部事件类型，用于构建事件订阅 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": "score_apply.created",
      "label": "贡献申请创建成功",
      "description": "通过开放平台提交贡献申请成功后触发。",
      "category": "score"
    },
    {
      "value": "score_apply.approved",
      "label": "贡献申请审批通过",
      "description": "贡献申请审批通过时触发。",
      "category": "score"
    },
    {
      "value": "score_apply.rejected",
      "label": "贡献申请审批不通过",
      "description": "贡献申请审批不通过时触发。",
      "category": "score"
    },
    {
      "value": "score_apply.complained",
      "label": "贡献申请申诉",
      "description": "贡献申请被申诉时触发。",
      "category": "score"
    },
    {
      "value": "score_apply.confirmed",
      "label": "贡献申请确认",
      "description": "贡献申请被确认时触发。",
      "category": "score"
    },
    {
      "value": "common.accountUnbound",
      "label": "账号解绑",
      "description": "三方账号与员工解绑时触发。",
      "category": "common"
    }
  ]
}

响应字段说明

字段	类型	说明
`statusCode`	int	状态码，100 表示成功。
`msg`	string	响应消息。
`data`	array	事件类型列表。
`data[].value`	string	事件类型标识符，用于订阅配置。
`data[].label`	string	事件类型的中文名称。
`data[].description`	string	事件触发时机的详细说明。
`data[].category`	string	事件分类：`task`（任务类）、`score`（贡献类）、`note`（便签类）或 `common`（通用类）。

使用场景：建议在 API Key 配置页面调用此接口，动态渲染事件类型多选框，避免硬编码事件列表。

事件 Data 字段详解

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

1. 任务类事件

task.created - 任务创建

字段	类型	说明
`taskId`	string (UUID)	任务唯一标识符。
`title`	string	任务标题。
`createdAt`	string	任务创建时间（ISO 8601 格式）。

{
  "eventType": "task.created",
  "timestamp": "1718620800",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "完成季度复盘",
    "createdAt": "2026-06-17T16:00:00"
  }
}

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

字段	类型	说明
`taskId`	string (UUID)	任务唯一标识符。
`eventType`	string	事件类型标识，与外层 `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 - 便签夹状态变更

字段	类型	说明
`noteId`	string (UUID)	便签业务 Id。便签类事件返回。
`packageId`	string (UUID)	便签包业务 Id。便签包类事件返回。
`folderId`	string (UUID)	便签夹业务 Id。便签夹类事件返回。

建议操作：接收到便签事件后，三方可根据事件类型调用便签或便签包详情接口获取最新数据。便签 Webhook 只表示对应业务操作已经成功完成，不保证回调到达顺序。

{
  "eventType": "note.updated",
  "timestamp": "1718635200",
  "data": {
    "noteId": "d4e5f6a7-b8c9-0123-defa-456789012345"
  }
}

3. 贡献类事件

score_apply.created - 贡献申请创建

字段	类型	说明
`applyId`	string (UUID)	贡献申请唯一标识符。
`applyType`	int	申请类型（具体类型值需参考贡献模块文档）。
`score`	decimal	申请贡献点数量。
`isAnonymous`	bool	是否匿名申请。
`createdAt`	string	申请创建时间（ISO 8601 格式）。

{
  "eventType": "score_apply.created",
  "timestamp": "1718628000",
  "data": {
    "applyId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "applyType": 1,
    "score": 5.0,
    "isAnonymous": false,
    "createdAt": "2026-06-17T17:00:00"
  }
}

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

字段	类型	说明
`applyId`	string (UUID)	贡献申请唯一标识符。
`statusCode`	int	业务状态码（100 表示成功）。
`msg`	string	状态变更说明信息（如审批意见）。

建议操作：接收到贡献申请状态变更事件后，三方可调用贡献申请详情接口获取完整信息（包括审批人、审批时间、贡献点变更记录等）。

{
  "eventType": "score_apply.approved",
  "timestamp": "1718631600",
  "data": {
    "applyId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "statusCode": 100,
    "msg": "审批通过"
  }
}

说明：score_apply.rejected、score_apply.confirmed、score_apply.complained 的 data 字段结构与上例一致，均返回 applyId、statusCode、msg。

4. 通用类事件

common.accountUnbound - 三方账号解绑

字段	类型	说明
`apiKeyId`	string (UUID)	API Key 唯一标识符。
`thirdPartyUserId`	string	三方系统的用户唯一标识。
`employeeVirtualId`	string	慧企星助平台员工虚拟 ID（解绑后该员工将无法再通过三方身份访问）。
`eventType`	string	事件类型标识，固定为 `"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 数据：

参数	类型	说明
`eventType`	string	事件类型，如 `task.created`。
`timestamp`	string	Webhook 发送时的 Unix 秒级时间戳字符串，例如 `"1718620800"`；该值同时用于签名验证与防重放校验。
`data`	object	事件详细数据（由具体事件类型决定，见上方"事件 Data 字段详解"）。

签名验证

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

Header 名称	说明
`X-Webhook-Signature`	HMAC-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 请求后，务必先验证签名，再处理业务逻辑。

重试机制

开放平台会对 Webhook 投递失败进行自动重试，最多重试 3 次：

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

如果 3 次重试后仍然失败，该事件将标记为投递失败，可在日志中查看详细信息。

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