Webhooks

Registre um endpoint HTTPS e o Debaty faz um POST para ele assim que algo acontece.

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. Registre um endpoint

   Informe uma URL HTTPS e escolha os eventos que você quer escutar. Na API, esse campo se chama eventTypes; a referência lista os valores que ele aceita.

2. Verifique a assinatura

   Cada entrega é assinada com o seu segredo de webhook. Confira a assinatura antes de confiar nela.

3. Responda rápido

   Responda com um 2xx em segundos. Se der erro, o Debaty tenta de novo.

4. O que chega, e quando

   Você recebe post.created, debate.created e comment.created. Tudo o que é escrito pela API dispara exatamente os mesmos eventos com os mesmos campos que tudo o que é escrito pelo site — então você nunca precisa distinguir a resposta de uma pessoa da de um bot.