Reconciliar eventos

Como a entrega por webhook é pelo menos uma vez, e não exatamente uma vez, a Routa oferece um segundo caminho para você conferir o que aconteceu: GET /v1/events. Ele transforma uma indisponibilidade de horas em uma recuperação determinística, sem pedir ajuda ao suporte.

Escopo necessário: events:read.

Quando usar

Seu servidor ficou fora do ar por mais tempo que a janela de retentativas (cerca de 20 horas).
Você suspeita de lacunas entre os eventos recebidos e o que aconteceu.
Você está ligando uma integração nova e quer carregar o histórico.
Você quer um job periódico de conferência como rede de segurança.

Como funciona

Guarde o id do último evento que você processou. Peça os eventos seguintes com after. Repita enquanto has_more for true.

curl "https://api.routa.chat/v1/events?after=evt_01J8ZK9M3Q7X...&limit=100" \
  -H "Authorization: Bearer $ROUTA_API_KEY"

let cursor = await loadLastProcessedEventId()

for await (const event of routa.events.list({ after: cursor, limit: 100 })) {
  await processEvent(event) // idempotente, deduplicando por event.id
  cursor = event.id
  await saveLastProcessedEventId(cursor)
}

Resposta

{
  "data": [
    {
      "id": "evt_01J8...",
      "type": "message.failed",
      "api_version": "v1",
      "schema_version": 1,
      "project_id": "proj_01J8...",
      "sequence": 918274,
      "occurred_at": "2026-09-04T13:23:00.000Z",
      "recorded_at": "2026-09-04T13:23:00.150Z",
      "data": { "id": "msg_01J8...", "status": "failed" }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Parâmetro	Descrição
`after`	Retoma depois deste id de evento.
`type`	Filtra por um tipo de evento.
`limit`	Itens por página, de 1 a 100.

Os eventos voltam em ordem crescente de sequence. Se o after não existir, a API retorna 404 event_not_found.

Processe de forma idempotente

Eventos obtidos por esta rota são os mesmos que o webhook entrega, com o mesmo id. Se você recebeu um evento por webhook e também o vê na consulta, a deduplicação por id evita processá-lo duas vezes.

Grave o id

Antes de aplicar o efeito, registre o id do evento em uma tabela com chave única, na mesma transação do efeito.

Ignore repetidos

Se o id já existir, pule o evento.

Respeite o status monotônico

Para eventos de mensagem, só avance o status. Nunca o rebaixe.

Retenção

Os eventos ficam disponíveis por 90 dias. Faça a reconciliação dentro desse prazo.

Comece aqui

Conceitos

Guias

Webhooks

Confiabilidade

Erros

Uso e cobrança

Reconciliar eventos

Quando usar

Como funciona

Processe de forma idempotente

Retenção

​Quando usar

​Como funciona

​Processe de forma idempotente

​Retenção

Quando usar

Como funciona

Processe de forma idempotente

Retenção