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.
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:
- Usa o corpo BRUTO. Se serializares o JSON outra vez, a assinatura deixa de bater — a ordem das chaves e os espaços mudam.
- Compara em tempo constante. Um
===sobre uma assinatura deixa medir, com tempo, onde as strings divergem. - 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.