Webhooks
O Placa & FIPE avisa o seu sistema, por um POST com JSON, quando algo acontece com o saldo da conta. Assim a sua aplicação não para por falta de saldo.
Configure em Painel → Configurações → Webhook para o seu sistema: informe uma URL https pública e use o botão Enviar teste.
Eventos
| Evento | Quando |
|---|---|
saldo.baixo | O saldo caiu abaixo do limite de alerta que você definiu. Dispara uma vez; volta a valer depois da próxima recarga. |
recarga.gerada | A recarga automática gerou um Pix. Vem o código copia e cola para pagar. |
saldo.recarregado | Um pagamento caiu e o saldo aumentou. |
teste | Você clicou em "Enviar teste" no painel. |
Formato
POST https://seusistema.com.br/webhooks/placaefipe
Content-Type: application/json
X-PlacaEFipe-Evento: saldo.baixo
X-PlacaEFipe-Assinatura: t=1794750000,v1=5f1c...e9{
"id": "evt_Qm3xK9pLw2Ze",
"evento": "saldo.baixo",
"criado_em": "2026-11-15T13:20:00.000Z",
"dados": { "saldo": 4.31, "saldo_texto": "R$ 4,31", "limite": 5 }
}recarga.gerada traz também valor, pedido_id, pix_copia_e_cola e expira_em. saldo.recarregado traz valor (o que foi pago) e o saldo novo.
Responda com qualquer 2xx em até 5 segundos. Não há novas tentativas: o painel mostra o status da última entrega. Para não perder nada, consulte também GET /v1/saldo.
Conferir a assinatura
O cabeçalho X-PlacaEFipe-Assinatura tem t (horário Unix) e v1 = HMAC-SHA256 do texto `${t}.${corpo}` com o segredo do painel (whsec_...). Use o corpo cru, antes de converter o JSON.
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
export function webhookValido(corpo, cabecalho, segredo) {
const partes = Object.fromEntries(cabecalho.split(',').map((p) => p.split('=')));
const esperado = createHmac('sha256', segredo).update(`${partes.t}.${corpo}`).digest('hex');
const recente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300; // 5 minutos
return recente && timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1 ?? ''));
}Python
import hmac, hashlib, time
def webhook_valido(corpo: bytes, cabecalho: str, segredo: str) -> bool:
partes = dict(p.split("=", 1) for p in cabecalho.split(","))
esperado = hmac.new(segredo.encode(), f"{partes['t']}.".encode() + corpo, hashlib.sha256).hexdigest()
recente = abs(time.time() - int(partes["t"])) < 300
return recente and hmac.compare_digest(esperado, partes.get("v1", ""))Recarga automática
Em Configurações → Recarga automática, escolha o valor (a partir de R$ 25) e informe nome, CPF e celular do pagador (a Cakto exige para gerar o Pix). Quando o saldo cair abaixo do limite do alerta, geramos o Pix desse valor e mandamos para o seu e-mail e para o webhook (recarga.gerada). O pagamento continua sendo seu: nada é debitado sem você pagar o Pix.
