Webhooks e eventos

Cadastre uma URL em Cobrança → Integração e o motor avisa seu sistema sobre tudo que importa. Toda entrega sai assinada com o mesmo secret (e o mesmo esquema de verificação) do endpoint de preço.

Catálogo de eventos

Evento	Quando dispara
invoice.issued	Fatura emitida no seu gateway
invoice.paid	Pagamento confirmado (conciliação com o gateway)
invoice.overdue	Venceu sem pagamento
invoice.held	Fatura retida aguardando valor — ação sua necessária
pricing.failing	Seu endpoint de preço falhando; retentativas em curso (payload traz o erro cru)
pricing.recovered	Seu endpoint voltou sozinho depois de um aviso — nada a fazer
subscription.canceled	Assinatura cancelada (payload traz o estado da fidelidade)

O envelope

Toda entrega (e todo item do replay) tem a mesma forma:

{
  "id": "01a04f…",
  "type": "invoice.issued",
  "occurredAt": "2026-08-29T20:00:00.000Z",
  "data": {
    "invoiceId": "…",
    "subscriptionId": "…",
    "totalCents": 105720,
    "gatewayInvoiceId": "22052146"
  }
}

O id do envelope é o mesmo cursor do replay. Os eventos de pricing carregam o customerExternalRef — o seu ID do cliente.

Replay: quem perdeu webhook não perde história

Todo evento fica disponível para consulta:

curl "$MOTOR/events?cursor=…" -H "$AUTH"

Caiu por uma hora? Consuma o GET /v1/events a partir do último cursor processado e reconstrua tudo. Entrega de webhook tem retentativa própria, mas o replay é a garantia final.

Teste

POST /v1/integration/alert-webhook/test (ou o botão na tela de Integração) envia um evento de exemplo e mostra a resposta do seu servidor.