
# 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

```http
POST https://seusistema.com.br/webhooks/placaefipe
Content-Type: application/json
X-PlacaEFipe-Evento: saldo.baixo
X-PlacaEFipe-Assinatura: t=1794750000,v1=5f1c...e9
```

```json
{
  "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

```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

```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.
