Webhooks (HMAC-SHA256)

O Typedit pode entregar eventos editoriais via webhook assinado (HMAC-SHA256) para sistemas externos da redação — CMS legado, ferramentas de BI, paywall, sistema de comentários ou qualquer consumidor que precise reagir a eventos editoriais em tempo quase-real.

Eventos disponíveis

• article.published — matéria foi aprovada e publicada.
• article.updated — matéria publicada foi alterada (correção, errata, etc.).
• article.unpublished — matéria foi removida do site (despublicação).
• dossier.completed — apuração concluída, dossiê de evidências disponível.
• editorial.flagged — afirmação foi marcada como divergente e aguarda decisão editorial.

Formato do payload

HTTP request
POST https://example.com/typedit-webhook
X-Typedit-Event: article.published
X-Typedit-Delivery: 8e1ab2f3-7c1c-4c6d-9b3a-1f5d2c4e8a9b
X-Typedit-Signature: t=1714000000,v1=<hex>
Content-Type: application/json

{
  "event": "article.published",
  "delivered_at": "2026-04-25T14:00:00Z",
  "data": {
    "article_id": "art_01HZ...",
    "workspace_id": "ws_01HZ...",
    "title": "...",
    "permalink": "https://exemplo-veiculo.com.br/...",
    "dossier_id": "dos_01HZ...",
    "author": { "id": "usr_01HZ...", "name": "..." }
  }
}

Verificação de assinatura

O header X-Typedit-Signature contém o timestamp do envio e a assinatura HMAC-SHA256 do payload concatenado, no formato t=<timestamp>,v1=<hex>. Use o segredo do webhook (configurado no painel) para verificar.

Node.js
import crypto from "node:crypto"

function verifyTypeditSignature(opts: {
  rawBody: string
  signatureHeader: string
  secret: string
  toleranceSeconds?: number
}): boolean {
  const tolerance = opts.toleranceSeconds ?? 300
  const parts = Object.fromEntries(
    opts.signatureHeader.split(",").map((p) => p.split("=")),
  )
  const t = Number(parts.t)
  const sent = parts.v1
  if (!t || !sent) return false
  if (Math.abs(Date.now() / 1000 - t) > tolerance) return false

  const expected = crypto
    .createHmac("sha256", opts.secret)
    .update(`${t}.${opts.rawBody}`)
    .digest("hex")

  return crypto.timingSafeEqual(
    Buffer.from(sent, "hex"),
    Buffer.from(expected, "hex"),
  )
}

Use comparação timingSafeEqual para evitar timing attacks. Tolerância de 5 minutos é o default — ajuste conforme sua tolerância a clock skew.

Retry policy

• Endpoints devem responder com 2xx em até 30 segundos para confirmação.
• Em caso de erro (4xx, 5xx ou timeout), o Typedit reentrega com backoff exponencial.
• Tentativas de reentrega: imediato, 30s, 5min, 30min, 2h, 8h. Após 6 falhas, o evento é marcado como indelivered e disponibilizado para inspeção manual.
• Cada reentrega usa o mesmo X-Typedit-Delivery — use-o para idempotência.

Idempotência

O header X-Typedit-Delivery é único por evento+entrega. Em caso de reentrega após falha, o mesmo Delivery ID é usado — o seu sistema deve ignorar reentregas que já foram processadas com sucesso.

Segurança

• Webhooks só são entregues sobre TLS 1.2+.
• O segredo HMAC é gerado por workspace e pode ser rotacionado a qualquer momento.
• IPs de origem ficam disponíveis para allowlist (sob solicitação).