Webhooks & 事件

实时事件。经 HMAC 签名投递。

一旦文档、作业、工作区或任务发生变更，PaperOffice 就会调用您的端点。无需轮询。

22 种事件类型、HMAC-SHA256 签名、三种重试策略以及每次尝试的投递日志。

订阅第一个 Webhook 发起首次 API 调用

每次投递均使用 HMAC-SHA256 最多10次重复（默认5次）通过事件ID实现幂等性

yourdomain.com/webhooks/paperoffice

POST /your-endpoint 200 OK HMAC-SHA256

请求头

X-PaperOffice-Eventdocument.processed
X-PaperOffice-Event-IDa3b7f9c1d4e8b2a6
X-PaperOffice-Signaturesha256=9f8a2c…

JSON主体

{
  "event_type": "document.processed",
  "event_id": "a3b7f9c1d4e8b2a6",
  "timestamp": "2026-04-17T14:23:11Z",
  "subscription_id": 42,
  "data": { "pofid": "doc_01HZY8K3…" }
}

可用事件

22种事件类型，按实体分组

订阅单个事件，或使用通配符 * 订阅所有事件。

文档

document.uploaded 新文档已上传至工作区
document.created document.uploaded 的别名（兼容性）
document.processed OCR-/AI-IDP-Pipeline 成功完成
document.edited 文档已编辑：元数据、标签或内容已更新
document.deleted 文档已移至回收站
document.restored 从废纸篓中恢复文档
document.moved 文档在工作区之间移动
document.version_created 现有文档的新版本
document.lifecycle_changed 保留/归档状态已更改
document.comment_added 已创建文档评论
document.note_added 已附加内部备注
document.tag_added 已为文档分配标签
document.legal_hold_placed 法律保留已启用（不可变）
document.legal_hold_released 法律保留已解除

作业

job.completed 异步作业成功完成
job.failed 异步作业最终失败
job.progress 较长任务的进度更新

Workspaces

workspace.shared 工作区与用户或团队共享
workspace.unshared 工作区访问权限被撤销

任务

task.created 创建了新任务
task.completed 任务标记为已完成
task.overdue 任务已超过截止日期

有效载荷和标头

每次投递都遵循相同的模式

可预测的JSON主体，固定的HTTP头，ISO-8601 UTC时间戳。

请求体

{
  "event_type": "document.processed",
  "event_id": "a3b7f9c1d4e8b2a6c9f1d4e7b2a5c8f1",
  "timestamp": "2026-04-17T14:23:11Z",
  "subscription_id": 42,
  "data": {
    "pofid": "doc_01HZY8K3M7P2Q9R5T1V6W4X2Y8",
    "workspace_id": 17,
    "filename": "invoice-2026-04-17.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 284521,
    "processing_result": {
      "ocr_done": true,
      "classification": "invoice",
      "confidence": 0.98
    }
  }
}

HTTP请求头

标题示例值含义

Content-Type application/json 始终为JSON，UTF-8编码

User-Agent PaperOffice-Webhook/1.0 防火墙白名单的固定标识符

X-PaperOffice-Event document.processed 已交付的事件类型

X-PaperOffice-Event-ID a3b7f9c1… 128位唯一ID。请将其用作幂等键。

X-PaperOffice-Subscription-ID 42 接收事件的订阅ID

X-PaperOffice-Signature sha256=… 原始请求体的HMAC-SHA256哈希值，十六进制编码

cURL

1curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \2  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "My Production Webhook",6    "url": "https://yourdomain.com/webhooks/paperoffice",7    "events": ["document.processed", "job.completed", "job.failed"],8    "retry_policy": "exponential",9    "max_retries": 5,10    "timeout_ms": 1000011  }'

1import crypto from 'crypto';2import express from 'express';34const app = express();5const WEBHOOK_SECRET = process.env.PAPEROFFICE_WEBHOOK_SECRET;67app.post('/webhooks/paperoffice', express.raw({ type: 'application/json' }), (req, res) => {8  const signature = req.header('X-PaperOffice-Signature'); // "sha256=..."9  const eventId   = req.header('X-PaperOffice-Event-ID');10  const eventType = req.header('X-PaperOffice-Event');1112  const expected = 'sha256=' + crypto13    .createHmac('sha256', WEBHOOK_SECRET)14    .update(req.body)15    .digest('hex');1617  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {18    return res.status(401).send('invalid signature');19  }2021  const event = JSON.parse(req.body.toString());22  // store eventId as idempotency key -> never process the same ID twice23  console.log(eventType, event.data);24  res.status(200).send('ok');25});

1import hmac, hashlib, os2from flask import Flask, request, abort34app = Flask(__name__)5WEBHOOK_SECRET = os.environ["PAPEROFFICE_WEBHOOK_SECRET"]67@app.route("/webhooks/paperoffice", methods=["POST"])8def paperoffice_webhook():9    signature  = request.headers.get("X-PaperOffice-Signature", "")10    event_id   = request.headers.get("X-PaperOffice-Event-ID", "")11    event_type = request.headers.get("X-PaperOffice-Event", "")1213    expected = "sha256=" + hmac.new(14        WEBHOOK_SECRET.encode(),15        request.get_data(),16        hashlib.sha256,17    ).hexdigest()1819    if not hmac.compare_digest(signature, expected):20        abort(401)2122    payload = request.get_json()23    # store event_id as idempotency key in your DB24    print(event_type, payload["data"])25    return "ok", 200

1<?php2// PaperOffice webhook receiver with HMAC-SHA256 signature verification3$secret = getenv('PAPEROFFICE_WEBHOOK_SECRET');4$raw    = file_get_contents('php://input');56$signature  = $_SERVER['HTTP_X_PAPEROFFICE_SIGNATURE'] ?? '';7$event_id   = $_SERVER['HTTP_X_PAPEROFFICE_EVENT_ID'] ?? '';8$event_type = $_SERVER['HTTP_X_PAPEROFFICE_EVENT'] ?? '';910$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);11if (!hash_equals($expected, $signature)) {12    http_response_code(401);13    exit('invalid signature');14}1516$event = json_decode($raw, true);17// store event_id as idempotency key in your DB18error_log("{$event_type}: " . json_encode($event['data']));19http_response_code(200);20echo 'ok';

签名验证

使用HMAC-SHA256验证每次交付

使用您的共享密钥对原始请求体计算HMAC-SHA256，并将结果与X-PaperOffice-Signature进行比较——必须使用恒定时间比较。

恒定时间比较
hash_equals、hmac.compare_digest或crypto.timingSafeEqual：比较过程不得泄露任何时间差异。
原始正文签名
签名适用于未更改的请求正文。请在验证后解析JSON，否则哈希值将不一致。
通过API订阅
POST /latest/webhooks/subscribe，包含name、url和events。如果secret留空，PaperOffice将生成它并一次性返回。

认证与密钥 Postman集合

重试与投递

三种重试策略，最多10次重试

为每个订阅选择策略。每次尝试都会记录状态码、响应正文和计时。

标准 exponential
指数退避（默认）

每次失败后，重试间隔时间翻倍。
linear
线性

重试间隔以固定步长增加。
none
无

不重试，即使是5xx错误（发送即忘）。适用于测试钩子。

成功在超时窗口内返回HTTP 2xx状态码
最大重试次数 最多10次重试（默认5次）
超时时间 每次尝试 1,000–30,000 毫秒（默认 10,000）
投递日志 每次尝试都会被记录；即使删除订阅，日志也会保留。

管理-API

五个端点位于 /latest/webhooks/ 下

创建、列出、更新和删除订阅——附带一个测试端点。每次调用都携带一个Bearer令牌。

POST /webhooks/subscribe 创建订阅；有效载荷使用 HMAC-SHA256 签名 MCP工具po-webhooks-subscribe
GET /webhooks/list 列出账户的所有Webhook订阅 MCP工具po-webhooks-list
POST /webhooks/update 更新 URL、事件、标头、重试策略或激活状态 MCP工具po-webhooks-update
POST /webhooks/delete 取消订阅；投递日志保留 MCP工具po-webhooks-delete
POST /webhooks/test 向订阅发送测试事件并检查投递情况 MCP工具po-webhooks-test

查看MCP服务器 Postman集合

安全

原生加固

六种在每次投递时生效的机制——由PaperOffice端和您端共同保障。

HMAC-SHA256
每次投递均使用您的密钥签名。比较必须在恒定时间内完成。
SSRF保护
在订阅和分发过程中，会阻止私有IP、内部IP、本地主机以及云元数据端点。
防止DNS重绑定
在分发时重新验证IP地址，并通过CURLOPT_RESOLVE进行固定。
推荐使用HTTPS
接受HTTP和HTTPS。对于生产环境，我们建议使用HTTPS。
通过事件ID实现幂等性
每次投递都附带唯一的X-PaperOffice-Event-ID。请在您的端进行去重处理。
完整的投递日志记录
所有尝试都会被记录：状态码、响应体、计时、错误消息。

限制

可配置每个订阅的交付行为

所有值在创建时或通过/webhooks/update设置——按订阅，而非按账户。

0–10 每次投递的重复次数（默认值：5）
1,000–30,000 毫秒 每次尝试的超时时间（默认 10,000）
3 重试策略：无、线性、指数
HMAC-SHA256 每次交付时签名

Webhooks 从 Professional 计划开始提供。价格概览将显示哪个计划适合您的设置。

查看价格认证与密钥

视频

Webhooks 实战演示

观看视频，了解 PaperOffice Webhooks 的实际工作原理。

常见问题

关于Webhook的常见问题

如何验证交付？

使用您的订阅密钥对原始请求正文计算 HMAC-SHA256，并以恒定时间将结果与 X-PaperOffice-Signature 标头（格式为 sha256=<hex>）进行比较。如果签名不匹配，请返回 HTTP 401 并忽略该正文。

秘密来自哪里？

在通过 POST /latest/webhooks/subscribe 创建订阅时，如果将 secret 字段留空，PaperOffice 将生成一个密钥并仅在响应中返回一次。您可以通过 POST /latest/webhooks/update 随时替换它。

如果我的端点没有响应，会发生什么？

任何非 HTTP 2xx 的响应或超时均计为失败尝试。根据重试策略（指数退避、线性、无），PaperOffice 会将投递重复至设定的最大重试次数（0–10，默认值为 5）。每次尝试的状态码、响应内容和耗时记录均在投递日志中。

同一投递是否会重复到达？

是的，在超时后的重试过程中可能发生重复。因此请通过 X-PaperOffice-Event-ID 进行去重：该 ID 对每个事件唯一，可用作数据库中的幂等键。

我可以订阅哪些事件？

来自四个类别的 22 种事件类型：文档、作业、工作区和任务。您可以订阅单个事件，或使用通配符 * 订阅所有事件。通过过滤器（如 workspace_id 或 pofid）可进一步限制订阅范围。

Webhooks 包含在哪个套餐中？

Webhooks 在 Professional 套餐及以上版本中提供。哪种套餐适合您的设置，请参阅价格概览。

运营与信任

企业团队在首次通话前检查的内容

合同、安全、支持和限制，所有链接集中一处。

下一站

后续步骤

开发者漏斗中推荐的下一步以及两个合适的分支。

Postman Collection在 Postman 中导入、测试和调试 Publishable Keys用于 AI Artifacts 和前端应用的浏览器安全 Keys 第一个 API 调用获取 Key，发送请求，检查响应

返回开发者入口

14 分钟了解 PaperOffice AI。

希望如何使用 PaperOffice？

实时事件。经 HMAC 签名投递。

22种事件类型，按实体分组

文档

作业

Workspaces

任务

每次投递都遵循相同的模式

使用HMAC-SHA256验证每次交付

三种重试策略，最多10次重试

指数退避（默认）

线性

无

五个端点位于 /latest/webhooks/ 下

原生加固

可配置每个订阅的交付行为

Webhooks 实战演示

关于Webhook的常见问题

企业团队在首次通话前检查的内容

后续步骤

实时事件。 经 HMAC 签名投递。

22种事件类型，按实体分组

每次投递都遵循相同的模式

使用HMAC-SHA256验证每次交付

三种重试策略，最多10次重试

指数退避（默认）

线性

无

五个端点位于 /latest/webhooks/ 下

原生加固

可配置每个订阅的交付行为

Webhooks 实战演示

关于Webhook的常见问题

企业团队在首次通话前检查的内容

后续步骤

实时事件。经 HMAC 签名投递。