Webhook 与结果回调：事件接入、验签和投递

POST <网关 origin，不含 /api/v1>/api/v1/webhooks/<integration_id>

{
  "type": "ticket.updated",
  "ticket_id": "ticket-42",
  "text": "Summarize this test ticket and suggest the next check. Do not modify external systems.",
  "data": {
    "ticket_id": "ticket-42",
    "summary": "A test device cannot connect after restart"
  }
}

ONEVIUM_WEBHOOK_URL=https://gateway.example.com/api/v1/webhooks/YOUR_INTEGRATION_ID
ONEVIUM_WEBHOOK_SECRET=PASTE_THE_INCOMING_WEBHOOK_SECRET

import { createHmac } from 'node:crypto';
import { readFile } from 'node:fs/promises';

const url = new URL(process.env.ONEVIUM_WEBHOOK_URL);
const secret = process.env.ONEVIUM_WEBHOOK_SECRET;
const eventId = process.argv[2];
if (!secret || secret.length < 32) throw new Error('Missing webhook secret');
if (!/^[\x21-\x7e]{1,128}$/.test(eventId || '')) throw new Error('Invalid event ID');
if (url.protocol !== 'https:' &&
    !(url.protocol === 'http:' && url.hostname === '127.0.0.1')) {
  throw new Error('Use HTTPS, or the displayed local loopback gateway');
}
const body = await readFile('ticket-event.json');
if (body.length > 1024 * 1024) throw new Error('Payload exceeds 1 MiB');
JSON.parse(body.toString('utf8'));
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac('sha256', secret)
  .update(`${eventId}.${timestamp}.`).update(body).digest('hex');
const response = await fetch(url, {
  method: 'POST',
  redirect: 'error',
  signal: AbortSignal.timeout(30_000),
  headers: {
    'Content-Type': 'application/json',
    'webhook-id': eventId,
    'webhook-timestamp': timestamp,
    'webhook-signature': `v1,${signature}`,
  },
  body,
});
console.log(response.status, await response.text());
if (!response.ok) process.exitCode = 1;

node --env-file=webhook.env send-ticket.mjs ticket-42-version-1

待签名字节 = UTF-8(event_id + "." + timestamp + ".") + 原始请求体字节
签名 = HMAC-SHA256(密钥原文的 UTF-8 字节, 待签名字节)

import http from 'node:http';
import { createHash, createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
import { mkdir, writeFile, readFile, link, unlink } from 'node:fs/promises';
import path from 'node:path';

const secret = process.env.ONEVIUM_CALLBACK_SECRET;
if (!secret || secret.length < 32) throw new Error('Missing callback secret');
const inbox = path.resolve('callback-inbox');
await mkdir(inbox, { recursive: true, mode: 0o700 });
const subscribed = new Set(['run.completed', 'run.failed', 'approval.required']);
const reject = (status) => Object.assign(new Error('Request rejected'), { status });

async function storeOnce(eventId, raw) {
  const name = createHash('sha256').update(eventId).digest('hex');
  const destination = path.join(inbox, `${name}.json`);
  const temporary = path.join(inbox, `${randomUUID()}.tmp`);
  try {
    await writeFile(temporary, raw, { flag: 'wx', mode: 0o600 });
    try {
      await link(temporary, destination);
    } catch (error) {
      if (error.code !== 'EEXIST') throw error;
      if (!(await readFile(destination)).equals(raw)) throw reject(409);
    }
  } finally {
    await unlink(temporary).catch(() => {});
  }
}

const server = http.createServer(async (request, response) => {
  try {
    if (request.method !== 'POST' || request.url !== '/onevium/events') {
      throw reject(404);
    }
    const id = request.headers['webhook-id'];
    const timestamp = request.headers['webhook-timestamp'];
    const supplied = request.headers['webhook-signature'];
    if (typeof id !== 'string' || !/^[\x21-\x7e]{1,128}$/.test(id) ||
        typeof timestamp !== 'string' || !/^\d{10,13}$/.test(timestamp) ||
        Math.abs(Date.now() / 1000 - Number(timestamp)) > 300 ||
        typeof supplied !== 'string' || !/^v1,[a-f0-9]{64}$/.test(supplied)) {
      throw reject(401);
    }
    const chunks = [];
    let size = 0;
    for await (const chunk of request) {
      size += chunk.length;
      if (size > 1024 * 1024) throw reject(413);
      chunks.push(chunk);
    }
    const raw = Buffer.concat(chunks);
    const expected = createHmac('sha256', secret)
      .update(`${id}.${timestamp}.`).update(raw).digest();
    if (!timingSafeEqual(expected, Buffer.from(supplied.slice(3), 'hex'))) {
      throw reject(401);
    }
    let event;
    try {
      event = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
    } catch {
      throw reject(400);
    }
    if (!event || event.event_id !== id || !subscribed.has(event.type) ||
        typeof event.run_id !== 'string' || typeof event.conversation_id !== 'string') {
      throw reject(400);
    }
    await storeOnce(id, raw);
    console.log(JSON.stringify({ event_id: id, type: event.type, stored: true }));
    response.writeHead(204).end();
  } catch (error) {
    response.writeHead(error.status || 500, { 'Content-Type': 'text/plain' })
      .end('Request rejected');
  }
});
server.requestTimeout = 15_000;
server.headersTimeout = 10_000;
server.maxConnections = 32;
server.listen(8789, '127.0.0.1', () => console.log('Callback receiver: 127.0.0.1:8789'));

node --env-file=callback.env callback-receiver.mjs