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

Transições de cobrança

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)

Ciclo de vida dos recursos

Toda mudança num recurso da conta também vira evento — inclusive as feitas pelo dashboard ou pelo MCP, não só as suas chamadas de API:

Evento	Quando dispara
invoice.created	Fatura gerada no chargeDay, ainda rascunho — antes de emitir no gateway
product.created / product.updated	Produto criado ou alterado — arquivar e desarquivar chegam como product.updated
plan.created / plan.updated	Plano criado; plan.updated cobre alteração, arquivamento e nova versão publicada
customer.created / customer.updated	Cliente novo na conta (primeira assinatura com aquele externalRef); updated após um PATCH /v1/customers
subscription.created / subscription.updated	Vínculo criado; updated cobre condições individuais e o avanço de ciclo — cancelar tem evento próprio
api_key.created / api_key.revoked	Chave de API criada ou revogada — trilha de auditoria da integração

O data desses eventos é o retrato atual do recurso no momento em que o evento é montado — a entrega é assíncrona, então duas mudanças rápidas podem chegar com o mesmo retrato final. A entrega é at-least-once e sem garantia de ordem: deduplique pelo id do envelope e trate o GET /v1/events como fonte de verdade.

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,
    "dueDate": "2026-09-18",
    "cycleDate": "2026-09-15",
    "gatewayInvoiceId": "22052146"
  }
}

O id do envelope é o mesmo cursor do replay. Em invoice.issued e invoice.overdue, dueDate é o vencimento da cobrança (cycleDate + expirationDays) e cycleDate é a âncora do ciclo. 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.