Eventos

Tudo que o motor conta pra você vira evento persistido. GET /v1/events devolve o histórico completo com cursor — inclusive o que o seu webhook perdeu. O corpo de cada evento é idêntico ao entregue no webhook; o push em si (cadastro, assinatura HMAC, catálogo) está no guia Webhooks e eventos.

Listar eventos (replay)

GET /v1/events

Query:

Parâmetro	Tipo	Padrão	Descrição
cursor	uuid	—	Id do último evento da página anterior — devolvemos os seguintes. Omitido, começa do início
type	string	—	Filtra por tipo de evento — ver valores
from	datetime	—	Só eventos a partir deste instante (ISO 8601)
to	datetime	—	Só eventos até este instante
limit	integer	50	Tamanho da página, 1 a 200

Resposta 200, mais antiga primeiro (é um stream, não uma lista):

Campo	Tipo	Descrição
data[]	array	Eventos em ordem de ocorrência
nextCursor	uuid | null	Cursor da próxima página — null quando acabou

Cada evento:

Campo	Tipo	Descrição
id	string (uuid)	Identificador do evento — é também o cursor
type	string	Tipo do evento — ver valores
occurredAt	datetime	Quando aconteceu
data	object	Payload do evento, o mesmo corpo entregue no webhook — exemplos no guia
delivery	object	Situação da entrega no seu webhook — ver abaixo

O objeto delivery:

Campo	Tipo	Descrição
delivery.status	enum	Ver valores
delivery.attempts	integer	Tentativas de entrega já feitas
delivery.deliveredAt	datetime | null	Quando o seu webhook aceitou (2xx)
delivery.lastError	string | null	Último erro de entrega, cru

Tipos de evento

Valor	Quando dispara
invoice.issued	Fatura emitida no seu gateway
invoice.paid	Pagamento confirmado (conciliação com o gateway)
invoice.overdue	Venceu sem pagamento, ou cobrança recusada
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 enum delivery.status

Valor	Significado
pending	Entrega em curso (ou na fila de retentativa)
delivered	Seu webhook aceitou com 2xx
failed	Retentativas de entrega esgotadas — o replay é a garantia
skipped	Nenhum webhook cadastrado na conta

O padrão de consumo

Guarde o último id processado e retome dali — caiu por uma hora, nada se perde:

# primeira página
curl "$MOTOR/events?limit=100" -H "$AUTH"

# seguintes: o nextCursor da resposta anterior
curl "$MOTOR/events?cursor=01a04f38-…&limit=100" -H "$AUTH"

# só pagamentos de um período
curl "$MOTOR/events?type=invoice.paid&from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00Z" -H "$AUTH"

O consumo é idempotente por natureza: o id do evento nunca muda, então processar duas vezes é seguro de detectar do seu lado.

Para testar a entrega no seu webhook, use POST /v1/integration/alert-webhook/test.