Saltar para o conteúdo

Webhooks

Receber um POST assinado quando algo acontece nos teus sites. Como subscrever, como verificar a assinatura, e o que fazemos quando o teu endpoint falha.

Avançado8 min de leitura

Subscrever

Em Desenvolvedor → Webhooks, ou pela API em /v1/me/webhooks. Uma subscrição tem:

  • URL — para onde mandamos. Tem de ser https://.
  • Nome — para ti.
  • Eventos — quais queres.
  • Sites (opcional) — só os eventos destes sites.

Ao criar, devolvemos o segredo de assinatura. É a única vez que ele aparece.

A forma do pedido

POST /o-teu-endpoint HTTP/1.1
Content-Type: application/json
X-FortFox-Event: origin.health.changed
X-FortFox-Delivery: 3f2a...c1
X-FortFox-Signature: t=1714824000,v1=a3f5b21c...

O corpo é um envelope com o id do evento, o tipo, a data e os dados:

{
  "id": "9d1f...",
  "type": "origin.health.changed",
  "created_at": "2026-09-01T10:30:00Z",
  "data": { }
}

Verificar a assinatura

O cabeçalho X-FortFox-Signature traz um t (a hora) e um v1 (a assinatura). A assinatura é o HMAC-SHA256 de t.corpo, com o teu segredo como chave.

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

function verificar(cabecalho, corpoBruto, segredo) {
  const partes = Object.fromEntries(
    cabecalho.split(',').map(p => p.split('=')),
  )
  const esperado = createHmac('sha256', segredo)
    .update(`${partes.t}.${corpoBruto}`)
    .digest('hex')

  // Comparação de tempo constante: um `===` deixa medir onde diferem.
  const a = Buffer.from(esperado)
  const b = Buffer.from(partes.v1 ?? '')
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false

  // E a janela de tempo: sem isto, uma entrega válida capturada hoje pode
  // ser reenviada daqui a um mês, com assinatura correcta.
  const idade = Math.abs(Date.now() / 1000 - Number(partes.t))
  return idade < 300
}

Três coisas que esse código faz e que valem a pena manter:

  1. Usa o corpo BRUTO. Se serializares o JSON outra vez, a assinatura deixa de bater — a ordem das chaves e os espaços mudam.
  2. Compara em tempo constante. Um === sobre uma assinatura deixa medir, com tempo, onde as strings divergem.
  3. Verifica a idade. É o que impede que uma entrega antiga, com assinatura legítima, seja reenviada mais tarde.

Responder

Responde 2xx depressa. Se o teu processamento demorar, aceita e trata depois: mantemos a ligação aberta enquanto esperamos, e um endpoint lento acaba a acumular tentativas.

Qualquer coisa que não seja 2xx — ou um tempo esgotado — conta como falha.

Tentativas

Cinco tentativas, com recuo crescente: de segundos a cerca de uma hora. A entrega leva sempre o mesmo X-FortFox-Delivery, o que te deixa reconhecer uma repetição.

O teu endpoint tem de ser idempotente. Não é uma sugestão: uma resposta perdida na rede produz uma segunda entrega do mesmo evento, e nós não temos como saber que a primeira chegou. Guarda os ids de entrega já processados.

Pausa automática

Cinco falhas seguidas — em qualquer evento — pausam a subscrição. O painel marca-a como pausada, e voltar a activá-la limpa o estado.

Existe para não gastarmos tentativas infinitas contra um endpoint que foi desligado, e para tu saberes que ele foi.

Depurar

/v1/me/webhooks/{id}/deliveries traz as entregas recentes: o que mandámos, o que recebemos, quantas tentativas, e o erro quando houve. É o primeiro sítio a olhar quando «não recebo nada».

Se as entregas estiverem lá com sucesso e nada chega ao teu lado, o problema está entre nós e o teu servidor — uma firewall, um proxy, um certificado.

O que fazer se o segredo vazar

Roda-o no painel. A rotação gera um novo e invalida o antigo de imediato; as entregas seguintes vêm assinadas com o novo.

Se tiveres o segredo em mais do que um sítio, actualiza-os todos — uma entrega assinada com o segredo novo falha a verificação em qualquer receptor que ainda use o antigo.

← Toda a documentação