API 参考

Webhooks

Numora 对外 API 开发者预览版中的 webhook 事件、签名、重试与投递处理方式。

范围

本页描述 Numora 对外 API 开发者预览版使用的 webhook 投递模型。

事件类型

支持的事件类型包括：

document.processing
document.review_required
document.reviewed
push.succeeded
push.failed
run.failed

事件示例

{
  "id": "evt_01jpx0wq5m6b3m2c9n8r5y2k7p",
  "type": "document.review_required",
  "created_at": "2026-03-21T14:24:11Z",
  "data": {
    "document_id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
    "schema": "invoice_v2",
    "status": "review_required"
  }
}

投递请求头

Webhook 请求应包含：

Content-Type: application/json
X-Numora-Webhook-Id: evt_01jpx0wq5m6b3m2c9n8r5y2k7p
X-Numora-Webhook-Timestamp: 2026-03-21T14:24:11Z
X-Numora-Webhook-Signature: t=2026-03-21T14:24:11Z,v1=abcdef123456

签名校验

推荐的验签流程：

读取原始请求体。
读取投递时间戳。
使用 webhook secret 重新计算 HMAC 签名。
将计算结果与收到的签名进行比较。
对签名无效或时间戳过期的请求直接拒绝。

重试行为

Webhook 接收端在事件被可靠接收后，应尽快返回 2xx。

如果投递失败，平台会按退避策略重试。接收方应将处理逻辑设计为幂等，并假设同一事件可能被投递多次。

事件顺序

接收方不应假设所有 webhook 投递都严格按全局顺序到达。

如果你关心的是资源当前最新状态，而不是事件到达顺序，应将 webhook 作为通知信号，再通过 API 拉取最新资源状态。

处理建议

在进入业务逻辑前先完成验签。
持久化事件 id，防止重复处理。
尽快返回 2xx，将耗时任务转交后台处理。
如果需要最准确的最新状态，可再调用 API 重新拉取资源。

相关页面

工作流与运行记录

说明 Numora 对外 API 开发者预览版中的 workflow list、dispatch、run status、run logs 与执行模型。

API 约定

对外 API 的通用约定，覆盖鉴权、幂等、webhook、错误模型、分页与异步处理。

On this page

投递请求头