Webhooks

Receba eventos do FreteFlow assim que acontecem.

Cadastrando um endpoint

Em Integrações → Webhooks, cadastre a URL HTTPS do seu endpoint e selecione os eventos que deseja receber. Você receberá um secret usado para assinar cada chamada.

Eventos disponíveis

freight.created
freight.published
freight.status_changed
offer.received / offer.accepted
driver.assigned
message.received / message.delivered

Verificando a assinatura

Cada requisição traz o header X-Webhook-Signature: HMAC-SHA256 do corpo cru da requisição usando seu secret. Sempre valide antes de processar:

import { createHmac, timingSafeEqual } from "crypto";

function verify(body: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Segurança

Nunca processe um webhook sem validar a assinatura. Atacantes podem forjar requisições para sua URL pública.

Retries

Se sua URL responder com status diferente de 2xx (ou demorar > 10s), o FreteFlow reagenda a entrega com backoff exponencial: 1min, 5min, 30min, 2h, 6h. Após 5 tentativas o evento é marcado como failed e fica disponível em Integrações → Eventos para reprocessamento manual.

Payload

json

{
  "id": "evt_01HABCDE...",
  "type": "freight.status_changed",
  "created_at": "2026-05-06T10:11:12Z",
  "data": {
    "freight_id": "FR-1234",
    "from": "in_transit",
    "to": "delivered"
  }
}