1. 基本概念

1.1 事件概述

📌

事件订阅适用于实时数据处理、快速事件响应等场景。例如：

某应用看板需要实时更新生产报工进度，希望能及时获取新核云生产报工数据，则可以订阅生产报工记录创建事件，当产生生产报工记录时，该应用可以第一时间获取报工工序、操作人、报工数量等信息，进而更新生产报工进度。

某审核应用需要及时响应生产单提交审核的数据，则可以订阅生产单创建事件。当生产单创建提交审核时，则发送审核通知信息，以便于第一时间处理审核任务。

某对接应用需要实时获取 MES 系统的生产完工入库记录，并及时推送给 ERP 系统完成相关成品库存数据的更新，则可以订阅出入库记录创建事件，当具体类型为 “生产入库” 或 “工序检验入库” 类型的出入库记录事件生成时，该应用就可以及时获取相关的生产单信息、成品数量、操作人、仓库、工序、质量状态等信息，从而保证 MES 系统和 ERP 系统的数据一致性。

同时，新核云开放平台提供了基于生产单创建信息的实时同步与自动化记录的业务场景的快速搭建教程，可以帮助您快速上手新核云开放平台事件订阅、API 调用功能与飞书工作流集成，从而实现数据实时同步与看板实时更新。

1.2 事件订阅与API调用的区别

特性	事件订阅 (Webhook)	API 调用
通信模式	被动接收 (由新核云主动推送)	主动获取 (由你的应用主动发起请求)
数据流向	新核云 → 你的服务器	你的服务器 → 新核云
最佳场景	实时通知、状态同步(当某事发生时)	按需查询、主动操作 (当你需要时)
时效性	高 (近实时，事件触发即推送)	依赖你的调用频率 (可能有过期数据)
数据关系	获取事件消息 (发生了什么，通常为变更数据)	获取资源状态 (是什么，通常为完整数据)
核心概念	订阅 (Subscribe) 一个事件	调用(Call) 一个接口

💡

用事件订阅 (Webhook)：如果你需要实时感知新核云内部发生的变化（事件驱动架构）。

用 API 调用：如果你需要主动去查询信息或执行操作。

在许多复杂的集成场景中（如快速开始文档中的业务场景），两者通常结合使用：

Webhook 用于触发：订阅生产单创建事件，接收实时通知。

API 用于补充：收到事件后，事件数据可能只包含关键ID，再调用查询生产单 API 获取该生产单的完整详细信息。

1.3 技术架构图

2. 消息体规范

2.1 通用消息头 (Headers) 结构

📌

租户 ID

人员 ID

时间戳（Timestamp）

业务类型代码

{
    "headers":{
         // 租户ID
        "TENANT_ID":[       
        ]
        // 人员ID
        "STAFF_ID":[       
        ]
         // 时间戳
        "x-nct-time":[     
        ]
         // 业务类型代码
        "business-type":[  
        ] 
}

消息头示例（采购申请单创建事件）

{
    "headers":{
         // 租户ID
        "TENANT_ID":[
            "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"  
        ]
        "STAFF_ID":[
            "123123"    
        ]
         // 时间戳
        "x-nct-time":[
            "1750351569887"   
        ]
         // 业务类型代码
        "business-type":[
            "9120"  
        ] 
}

2.2 通用消息体 (Payload) 结构

📌

请求 ID

业务类型

事件特定数据

{
  "requestId": "", // 请求唯一标识
  "businessType": , // 业务类型
  "data": {        //事件特定数据
  
  }
}

消息体示例（采购申请单创建事件）

{
  "requestId": "3a528d8b-8a9f-41ac-9306-3ca84fcc2985", // 创建请求唯一标识
  "businessType": 2010, // 业务类型：采购申请单创建
  "data": {
    "id": 10558833, // 申请单唯一ID
    "code": "PR-250620-007", // 采购申请单编号（PR-年月日-流水号）
    "type": 2, // 申请单类型（整数型标识）
    "status": 0, // 申请单状态（0通常表示草稿）
    "staffCode": "EM001", // 申请人员工工号
    "createTime": 1750391230000, // 创建时间戳（毫秒）
    "comments": null, // 申请单备注说明（空值）
    "extendedFields": [], // 扩展字段列表（空数组）
    "records": [ // 申请物料明细
      {
        "id": 13178611, // 明细项ID
        "itemId": "7308337992085815296", // 物料唯一ID（长整型）
        "itemCode": "复现mrp", // 物料编码
        "itemUnit": "瓶", // 物料计量单位
        "supplierCode": "", // 建议供应商编码（空值）
        "quantity": 1, // 申请采购数量
        "confirmQuantity": 0, // 采购确认数量（初始0）
        "deadline": 1750348800000, // 物料需求截止时间
        "latestCreateOrderDate": 1750262400000, // 最晚创建采购订单时间
        "sourceOrderNumber": null, // 来源订单号（空值）
        "procedureName": null, // 相关工序名称（空值）
        "procedureCode": null, // 相关工序编码（空值）
        "extendedFields": [] // 明细扩展字段（空数组）
      }
    ]
  }
}

2.3 Webhook 推送第三方配置详解

2.3.1 额外请求头 (Additional Headers)

为满足不同业务场景的集成需求，本平台允许您在创建事件订阅应用时，自定义一组额外的HTTP请求头。这些请求头将与系统默认的请求头一同包含在发送给您指定Webhook地址的请求中。

默认系统请求头

📌

无论您是否配置自定义头，新核云平台发出的所有Webhook事件请求都会包含以下系统默认头信息，用于描述事件基本元数据和进行安全验证：

Content-Type: 标识请求体的媒体类型。固定为 application/json，表明请求体为JSON格式的字符串。

Authorization（部分含有）：包含Bearer Token，用于接收方验证请求的合法性。其格式为：Bearer 您的应用Secret。请注意：此Token由系统自动生成并添加，您无需也不能在自定义头中重复配置Authorization。

TENANT_ID: 用于标识租户。

STAFF_ID: 用于标识触发事件的用户。

x-nct-time: 请求发出时的UTC时间戳（Unix Timestamp，单位为秒），用于与x-nct-sig配合进行签名验证，防止重放攻击。

x-nct-sig: 基于请求体、时间戳和您的应用Secret计算的数字签名。接收方应使用相同算法验证此签名，以确保消息未被篡改且来源可信。

business-type: 用于标识业务线。

您可以通过点击订阅事件应用的详情按钮查看 webhook 日志来查看默认系统请求头。

自定义请求头

您可以根据自身系统的需要，在应用配置页面定义额外的键值对（Key-Value）作为自定义请求头。例如：

📌

您的Webhook接收端服务有多个版本（如v1, v2），您希望通过请求头将流量分发到不同版本进行灰度发布或A/B测试。

X-API-Version: v2.1

X-Channel: production (或 canary, staging)

完整请求头示例：

以下是一些自定义请求头的示例：

自定义请求头	主要用途	示例值
`X-API-Version`	版本控制、路由	`v2.1`, `v3`
`Idempotency-Key`	幂等性控制，防重复	`webhook_evt_9876543210`
`X-Trace-ID`	分布式系统链路追踪	`00-<trace_id>-<span_id>-01`
`X-Event-ID`	事件唯一标识，用于查询	`event_abcd1234`
`X-Environment`	标识来源环境	`PROD`, `UAT`, `DEV`
`X-Trigger-Module`	标识触发业务模块	`MES_Work_Order`, `WMS_Inventory`
`其他任何您业务系统需要的固定标识符或令牌`

您可以根据实际的业务集成需求，选择性地添加自定义头，使得Webhook的接收方能够更智能、更安全、更高效地处理事件消息。

请避免使用 Content-Type, Authorization, x-nct-time, x-nct-sig 等系统保留字段作为您的自定义头名称，以免发生冲突。系统生成的头将覆盖您自定义的同名头。

2.3.2 推送超时时间 (Timeout)

📌

为确保平台服务的稳定性，新核云向第三方推送 Webhook 事件时有网络超时限制。

超时时间：单次推送请求的默认超时时间为 15 秒（不可在平台更改，如需更改请联系官方客服）。

重试策略：若因网络问题或接收方服务繁忙，在超时时间内未收到正确的 HTTP 200 响应，系统会自动触发重试，达到最大重试次数（3次）后新增一条失败日志记录。

最佳实践建议：

您的 Webhook 接收接口应设计为快速响应。建议在接收到事件后立即返回 HTTP 200 状态码，然后将耗时的事务处理（如写入数据库、调用其他API）放入后台队列异步执行。

请确保您的接收服务有足够的处理能力和稳定的网络，以避免因超时导致的重复推送。

2.3.3 异步更新日志状态 (Async Log Status)

🧷

为满足客户方复杂业务处理的集成需求，新核云提供了由客户方主动触发的日志状态更新机制。

状态更新逻辑：当新核云向客户方推送Webhook事件后，若在超时时间内未收到成功的HTTP响应，平台会自动将该次推送记录为“失败”状态。此后，客户方可在其内部系统完成后续处理后，主动调用新核云提供的更新事件日志状态 API，将对应的Webhook日志状态修改为“成功”。

核心流程：

新核云推送事件 -> 客户方响应超时 -> 新核云记录“失败”日志

客户方异步处理业务

客户方处理完成后 -> 调用“更新事件日志状态”API -> 新核云将日志状态更新为“成功”

设计目的：此设计将事件推送与业务处理解耦，允许客户方根据自身系统处理能力进行异步操作，避免因处理耗时而导致的重复推送，同时保证最终状态的可控性与一致性。

2.3.4 推送至 Coze 平台对接指南

🌟

您可以将新核云的事件推送至 Coze 平台的工作流（Workflow），触发自动化的业务处理与响应，例如：自动通知、数据同步、智能分析或生成报告等，进一步发挥新核云产品的数据流通性与新核云 AI 智能的协同效应，提升业务效率和团队响应速度。

对接方法

在 Coze 中创建工作流

在 Coze 中新建工作流（如已有工作流请忽略），查询工作流 Flow ID，如下图所示：

在新核云中配置 Webhook 订阅

请参考事件订阅配置与流程步骤三，平台选择 COZE，填入我们的 Flow ID，点击保存。

在 Coze 工作流中处理事件

Webhook 触发器节点接收到新核云的事件后，其输出将成为后续节点的输入。

您可以在工作流中后续添加 LLM大模型、代码、API请求 等节点，来解析和处理新核云的事件数据，并执行所需的业务逻辑。

3. 调试技巧：查看事件订阅日志

查看路径：开放平台 → Webhook，点击相应事件的详情按钮，在左上角切换到 webhook 日志

在 webhook 日志列表中选择相应事件日志，点击详情可以查看事件基本信息

在基本信息中点击请求参数，可以看到请求头与请求体结构。

新核云开放平台也支持查看所有订阅事件日志总览，查看路径：开放平台 → Webhook → 订阅事件日志

📌

事件订阅重发（Resend）：

针对已失败（如发送超时、接收方拒绝、网络异常等）的事件记录，主动触发一次或多次重新发送操作，尝试将事件重新传递至目标订阅方。例如：

事件因临时网络波动、接收方服务短暂不可用等原因首次发送失败；

接收方明确提示“可重试”；

需通过重发机制保障事件最终可达性。

📌

事件订阅强制成功（Force Success）：

手动将状态为“失败”或“未确认”的事件强制标记为“成功”，跳过实际发送流程或覆盖原始失败状态。例如：

事件实际已发送成功，但因日志记录延迟或系统误判显示为失败；

接收方已离线但后续人工确认已通过其他渠道补传，需修正日志状态；

测试或调试场景下，跳过失败事件以快速推进流程（需谨慎使用）。

4. 获取帮助

访问新核云社区——开放平台提问

事件订阅参考

1. 基本概念#

1.1 事件概述#

1.2 事件订阅与API调用的区别#

1.3 技术架构图#

2. 消息体规范#

2.1 通用消息头 (Headers) 结构#

消息头示例（采购申请单创建事件）#

2.2 通用消息体 (Payload) 结构#

消息体示例（采购申请单创建事件）#

2.3 Webhook 推送第三方配置详解#

2.3.1 额外请求头 (Additional Headers)#

默认系统请求头#

自定义请求头#

2.3.2 推送超时时间 (Timeout)#

2.3.3 异步更新日志状态 (Async Log Status)#

2.3.4 推送至 Coze 平台对接指南#

3. 调试技巧：查看事件订阅日志#

4. 获取帮助#