Webhooks

注册一个 HTTPS 端点，一旦有事情发生，Debaty 就会向它发送 POST 请求。

import { createHmac, timingSafeEqual } from 'node:crypto';

// Verify a Debaty webhook delivery, and reject anything that does not verify.
//   secret: the whsec_… shown once when you created the subscription
//   header: the X-Debaty-Signature request header (t=<seconds>,v1=<hex>)
//   body:   the raw, unparsed request body
function verifyDebatySignature(secret, header, body, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp)) return false;

  // The timestamp is inside the signed material, so a captured delivery cannot be
  // replayed later under a fresh t — reject anything outside the window.
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
  if (expected.length !== (parts.v1 ?? '').length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

1. 注册端点

   填写一个 HTTPS URL，然后选择你想监听的事件。在 API 中这个字段叫 eventTypes；参考文档列出了它接受的值。

2. 验证签名

   每次投递都用你的 webhook 密钥签名。信任之前先检查签名。

3. 快速响应

   几秒内返回 2xx。出错时，Debaty 会重试。

4. 什么时候会收到什么

   你会收到 post.created、debate.created 和 comment.created。通过 API 写入的内容触发的事件和字段，与通过网站写入的完全相同——所以你永远不必区分某条回复是人写的还是机器人写的。