跳到主要内容

事件幂等与事件收件箱

事件幂等与 EventKey​

Webhook 请求的幂等键（eventKey）由以下规则决定（参考 resolveEventKey）：

优先从请求头中读取：

  • X-Event-Id
  • X-Request-Id
  • X-Idempotency-Key

按顺序取第一个非空值作为 eventKey；若都不存在，则对请求体做 SHA-256 哈希作为 eventKey。

同一个 Trigger 下，eventKey 相同的事件会被视为重复，返回 duplicate = true，可用于避免重复消费。

Webhook 请求负载解析​

负载解析逻辑（参考 parsePayload）：

  • 若请求体为空，则触发器收到的 payload 为 {}（空对象）
  • 若 Content-Type 包含 application/json 且 JSON 解析成功：
    • payload 为 JSON 对象，字段按原样传递给工作流
  • 否则：

    • payload 形如：

      {
        "raw": "<按 UTF-8 解码的文本>",
        "base64": "<原始字节的 Base64 编码>"
      }

Webhook 响应结构​

Webhook 触发接口统一返回：

{
  "success": true,
  "data": {
    "accepted": true,
    "duplicate": false,
    "eventInboxId": "inbox_123",
    "workflowExecutionId": "exec_456"
  }
}
  • accepted：是否成功写入事件收件箱并进入调度流程
  • duplicate：是否检测到 eventKey 重复
  • eventInboxId：事件收件箱记录 ID
  • workflowExecutionId：对应的工作流执行 ID（若已经启动）

事件收件箱（TriggerEventInbox）​

查看指定 Trigger 的事件列表：

  • GET /linker/triggers/<triggerId>/events?page=&size=

返回字段（参考 TriggerEventSummary）：

  • items：事件列表，每个元素包含：
    • id：事件 ID
    • eventKey：幂等键
    • status：处理状态（枚举值，如 PENDING / RUNNING / DONE / FAILED 等）
    • attempts：重试次数
    • workflowExecutionId：绑定的工作流执行 ID
    • lastError：最近一次错误信息（若有）
    • payloadHash：请求负载哈希（用于排查）
    • createdAt / updatedAt：时间戳
  • page：当前页号（从 0 开始）
  • size：当前页大小
  • total：总条数