开发者文档中心

OpenAPI进入控制台

服务端 API 与回调 · 2026-10-31

业务回调接入:验签、去重与故障恢复

从订阅到持久收件箱的完整接入路径;明确回执、重试和业务处理的边界。

准备与接入

  1. 先在 API 平台读取真实事件和订阅;按实际需求给服务端密钥授予 callbacks.read,以及必要的 save / toggle / test 等操作。API Key 调用者须为企业管理员本人,并同时具备 applications、agent、service 权限;后台登录会话管理要求 applications 和 agent,具体事件另查对应权限。
  2. 使用 callbacks.save 保存公开 HTTPS 443 接收地址、非空 events 和 eventScope(self 或 tenant,默认 self)。新订阅停用;一次性 secret 放入接收端密钥存储,不放前端、日志或代码库。
  3. 下载接收、验签、收件箱三个文件并保持同目录;Node.js 24 下在服务启动时显式打开持久收件箱一次,POST 路由在 JSON 中间件之前把原始 Request 交给 receiveBusinessCallback。
  4. 配置固定的 inboxScope、tenantId 和允许的 actorId;企业事件范围使用可信配置中的 actorIds 白名单,不能从本次未验证正文复制 actorId 作为预期值。接收路径由自己定义,平台没有通用 /v1/webhooks/events 入站接口。
  5. 读取当前 revision,再用 callbacks.toggle 启用,callbacks.test 发送一次真实 webhook.test;从 callbacks.read 核对投递和 delivery 查询的逐次尝试,最后查询自己的持久收件箱。测试回调属于真实外发,代码导入与阅读文档不会自动发送。

API Key 的操作入口

操作参数与结果注意
GET /v1/operations/callbacks.readsubscriptions、deliveries、events;?delivery=投递ID 返回 attempts只读不推进队列;列表最多返回最近100条投递。
POST /v1/operations/callbacks.savename、endpoint、events、eventScope;更新另传 id、revision每人最多5个订阅;首次或传入非空 endpoint(含相同地址)均轮换并返回 secret;更新省略 endpoint 才保留原密钥。
POST /v1/operations/callbacks.toggleid、revision、enabled每次操作后重读最新 revision;不要猜测版本号。
POST /v1/operations/callbacks.testid、revision → eventId真实外发;每人每分钟最多10次。
POST /v1/operations/callbacks.dispatch{} → queued提交投递唤醒请求,每分钟最多10次;后台按当前授权统一处理,queued 不等于 delivered。
POST /v1/operations/callbacks.retryid、revision、deliveryId只允许未改配置的 dead 记录,累计少于10次;人工操作后仍需核对。
POST /v1/operations/callbacks.rotate / callbacks.deleteid、revision轮换会停用,重新部署密钥并确认启用;删除不可恢复。

写入与幂等

所有 /v1/operations 写请求使用服务端 Bearer、application/json 和稳定的 Idempotency-Key。网关按操作补齐 action,显式传入时必须匹配。一个业务尝试保持同一标识与相同请求;超时先查记录,不用新标识重复测试、轮换或重发。后台 /api/business-callbacks 使用登录会话,是另一种认证协议。

接收与快速回执

运行前

business-callback-receiver.mjs · 服务端接收模块

  • Node.js 24;与 verify-business-callback.mjs 放在同一目录。
  • 在 JSON 中间件之前调用;secret、tenantId、actorId 或 actorIds 和 inboxScope 由服务端可信配置提供。
完整代码 · 61 行
business-callback-receiver.mjsJavaScript
/** Server-only Webhook receiver. Importing this module opens no server or connection. */
import { createHash } from 'node:crypto';
import { verifyBusinessCallback } from './verify-business-callback.mjs';

const MAX_BYTES = 65536;
class BodyError extends Error {
  constructor(status) { super('CALLBACK_BODY'); this.status = status; }
}
async function readBody(request) {
  if (Number(request.headers.get('content-length')) > MAX_BYTES) throw new BodyError(413);
  if (!request.body) throw new BodyError(400);
  const reader = request.body.getReader();
  const chunks = [];
  let size = 0;
  try {
    for (;;) {
      const {done, value} = await reader.read();
      if (done) break;
      size += value.byteLength;
      if (size > MAX_BYTES) throw new BodyError(413);
      chunks.push(Buffer.from(value));
    }
    return Buffer.concat(chunks, size);
  } catch (error) {
    void reader.cancel().catch(() => {});
    throw error;
  } finally { reader.releaseLock(); }
}
const reply = (status, body) => Response.json(body, {
  status, headers: {'Cache-Control':'no-store', ...(status === 503 ? {'Retry-After':'30'} : {})},
});

/**
 * Call from an explicitly configured POST route BEFORE JSON middleware.
 * persist must atomically insert a durable inbox row with its unique deduplication
 * key and return inserted / duplicate / conflict. Never use a process-local Set.
 * inboxScope is a fixed, server-owned integration ID; do not read it from headers.
 * actorIds is an optional trusted allowlist for tenant-scope subscriptions.
 * Configure body-read deadlines at the HTTP server/proxy; no business work here.
 */
export async function receiveBusinessCallback({request, secret, tenantId, actorId, actorIds, inboxScope, persist}) {
  if (!secret || !tenantId || (!actorId && !actorIds?.length) || !inboxScope || typeof persist !== 'function')
    throw new Error('CALLBACK_CONFIGURATION_REQUIRED');
  if (request.method !== 'POST') return new Response(null, {status:405, headers:{Allow:'POST'}});
  if (request.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json')
    return reply(415, {error:'JSON_REQUIRED'});
  let rawBody;
  try { rawBody = await readBody(request); }
  catch (error) { return reply(error instanceof BodyError ? error.status : 400, {error:'INVALID_BODY'}); }
  let event;
  try { event = verifyBusinessCallback({secret, headers:request.headers, rawBody, tenantId, actorId, actorIds}); }
  catch { return reply(400, {error:'INVALID_CALLBACK'}); }
  const bodyHash = createHash('sha256').update(rawBody).digest('hex');
  try {
    const outcome = await persist({inboxScope, eventId:event.id, bodyHash, event});
    if (outcome === 'conflict') return reply(409, {error:'EVENT_BODY_CONFLICT'});
    if (outcome !== 'inserted' && outcome !== 'duplicate') return reply(503, {error:'INBOX_UNAVAILABLE'});
    // This acknowledges durable receipt only. A separate worker handles business work.
    return reply(200, {received:true, duplicate:outcome === 'duplicate'});
  } catch { return reply(503, {error:'INBOX_UNAVAILABLE'}); }
}
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    Node.js 24;与 verify-business-callback.mjs 放在同一目录。 在 JSON 中间件之前调用;secret、tenantId、actorId 或 actorIds 和 inboxScope 由服务端可信配置提供。

  2. 在项目中使用

    business-callback-receiver.mjs · 服务端接收模块

  3. 核对结果

    只有持久收件箱确认插入或重复后返回 200;冲突返回 409,存储故障返回 503;不执行业务副作用。

预期结果:只有持久收件箱确认插入或重复后返回 200;冲突返回 409,存储故障返回 503;不执行业务副作用。

持久化去重适配器

运行前

business-callback-inbox-postgres.mjs · PostgreSQL 持久化适配器

  • 使用 pg 驱动;传入专用 Pool,配置 PostgreSQL URL、TLS 和独立 schema。
  • 启动时 await openBusinessCallbackInbox(pool),把 inbox.persist 传给接收模块;退出时 await inbox.close()。
完整代码 · 25 行
business-callback-inbox-postgres.mjsJavaScript
/** PostgreSQL inbox. Pass a dedicated pg Pool with its TLS and schema configured by the host. */
export async function openBusinessCallbackInbox(pool) {
  if (!pool || typeof pool.query !== 'function' || typeof pool.end !== 'function')
    throw new Error('POSTGRES_INBOX_POOL_REQUIRED');
  try {
    await pool.query(`CREATE TABLE IF NOT EXISTS yunfu_callback_inbox (
      integration TEXT NOT NULL, tenant TEXT NOT NULL, event_id TEXT NOT NULL,
      body_hash TEXT NOT NULL, payload TEXT NOT NULL, received_at BIGINT NOT NULL,
      state TEXT NOT NULL DEFAULT 'pending', PRIMARY KEY(integration, tenant, event_id)
    )`);
  } catch (error) { await pool.end(); throw error; }
  return {
    // Unique insert includes the pending work payload; 2xx always follows persistence.
    async persist({inboxScope, eventId, bodyHash, event}) {
      const result = await pool.query(`INSERT INTO yunfu_callback_inbox
        (integration,tenant,event_id,body_hash,payload,received_at) VALUES($1,$2,$3,$4,$5,$6)
        ON CONFLICT(integration,tenant,event_id) DO NOTHING`,
        [inboxScope,event.tenantId,eventId,bodyHash,JSON.stringify(event),Date.now()]);
      if (result.rowCount === 1) return 'inserted';
      const prior = await pool.query('SELECT body_hash FROM yunfu_callback_inbox WHERE integration=$1 AND tenant=$2 AND event_id=$3', [inboxScope,event.tenantId,eventId]);
      return prior.rows[0]?.body_hash === bodyHash ? 'duplicate' : 'conflict';
    },
    close() { return pool.end(); },
  };
}
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    使用 pg 驱动;传入专用 Pool,配置 PostgreSQL URL、TLS 和独立 schema。 启动时 await openBusinessCallbackInbox(pool),把 inbox.persist 传给接收模块;退出时 await inbox.close()。

  2. 在项目中使用

    business-callback-inbox-postgres.mjs · PostgreSQL 持久化适配器

  3. 核对结果

    同一集成、企业、事件只生成一条待处理记录;跨重启保留去重,业务处理和保留期由宿主另外实现。

预期结果:同一集成、企业、事件只生成一条待处理记录;跨重启保留去重,业务处理和保留期由宿主另外实现。

接收后如何处理

示例仅持久保存 pending 事件,不启动业务工作进程,也不承诺业务恰好执行一次。宿主需另行实现领取、租约、重试与完成标记;向外部业务写入时使用其幂等键或事务约束,结果未知先核对。读取旧事件不能仅靠到达顺序;按 sourceId/taskId 和 revision 判断新旧。

inboxScope 应在同一集成的密钥轮换和重复部署间保持稳定;多租户、多个集成分别隔离。单机 SQLite 文件需要持久卷、文件权限和备份;多实例使用共享数据库的原子唯一写入,不能各开一份文件或用内存 Set。数据库示例不自动删除记录;保留期须覆盖自动与人工重试及业务审计要求。

宿主 HTTP 服务器应配置正文读取超时和连接上限。接收示例最多读取65536字节,先验签再解析,成功持久化后立即返回200;耗时业务放到独立工作进程。数据库出错返回503,不提前确认收到。

状态与排查

观察到的情况优先检查恢复方式
验签失败 / 400原始字节、sha256= 前缀、Unix秒时间戳、±300秒时钟差、当前 secret修正接收端;不要重新序列化正文再计算签名。
409 EVENT_BODY_CONFLICT同一集成/企业/事件编号对应不同原始正文保留原记录并告警,人工核查;不覆盖、不重复执行业务。
503 INBOX_UNAVAILABLE持久文件权限、容量、锁竞争或共享数据库连接恢复存储后由平台重试;200必须在持久化成功后返回。
retry / 网络超时接收方可能已持久保存,但回执丢失依靠事件ID和正文摘要去重,重复同正文返回200。
dead最多5次自动尝试耗尽,或发送中租约过期且次数耗尽修正故障后仅对允许的记录人工 retry,累计上限10次。
cancelled订阅停用/版本变化、账号epoch/权限、企业状态修复配置并重新确认启用;旧事件不会自动重放到新订阅。

时限和标识

单次投递总超时8秒,租约60秒。失败间隔30秒、2分钟、10分钟、1小时,最多5次含首次;实际执行时间还取决于调度与积压,不承诺秒级送达。至少一次、不保序。重试复用 Event-Id 和 Delivery-Id,刷新 Timestamp / Signature / Attempt;这些投递头本身不在正文签名范围内,去重以验签后的正文事件编号为准。接收方的 Retry-After 当前不调整平台固定重试表。

2xx只代表接收方确认收到,不代表退款、工单、构建或通话完成。api.request.completed 表示 API HTTP 处理结果;业务完成读取对应业务状态或对应已实现事件。错误诊断只记录事件/投递编号、状态和时间,避免记录密钥或敏感正文。

实现依据 · 仓库内路径
  • sdk/business-callback-receiver.mjs
  • sdk/business-callback-inbox-postgres.mjs
  • examples/verify-business-callback.mjs
  • backend/services/developer-api/callback-dispatch.ts
  • database/stores/callback-store.ts
  • backend/services/developer-api/callback-settings.ts
  • lib/developer-api/developer-operations.ts

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。