Esta página descreve a semântica de entrega: quando uma notificação é considerada entregue, como e quando ela é reentregue, e por que você nunca deve assumir ordem.

​
O que conta como entregue

Uma entrega é bem-sucedida se e somente se o receiver responde com qualquer 2XX em até 5 segundos do envio da requisição.
Redirects (3xx) não são seguidos e contam como falha. Timeouts, erros de conexão, 4xx e 5xx também são falhas — e qualquer falha dispara o schedule de retry abaixo.

​
Schedule padrão de retry

Para todos os eventos exceto item/login_succeeded, são até 9 tentativas distribuídas em 3 fases: Esgotadas as 9 tentativas, o evento é descartado permanentemente. A partir daí, a única forma de recuperar é reconciliar via GET /items/{id} e GET /transactions (veja a reconciliação noturna abaixo).

​
Exceção: item/login_succeeded

O item/login_succeeded é entregue no máximo 3 vezes no total, sem backoff por hora. É uma dica transitória de UX — uma entrega atrasada não teria utilidade. Se as 3 tentativas imediatas falharem, o evento é descartado.

​
Idempotência por eventId

  • Toda entrega carrega um eventId (UUID).
  • O mesmo eventId é reusado em todas as reentregas de um evento e em todos os endpoints assinantes (ex.: um webhook de all e um de item/error recebem o mesmo eventId para a mesma ocorrência).
  • O receiver deve persistir o eventId e tratar duplicatas como no-op antes de aplicar qualquer efeito colateral.
  • A reentrega manual pelo Dashboard também reusa o eventId original.

​
Sem garantia de ordenação

As entregas não são ordenadas. Nunca assuma ordem entre eventos — reconcilie sempre re-buscando o recurso canônico na API REST (esse é o padrão webhook como gatilho, REST como fonte da verdade).

​
Página de Eventos no Dashboard

O Dashboard tem uma página de Eventos que mostra cada entrega tentada:
  • Atualização automática a cada minuto.
  • Filtros por intervalo de datas, tipo de evento, Application Client ID, Item ID e texto livre.
  • Cada linha expõe o status HTTP retornado pelo receiver, o número de tentativas feitas, o próximo retry agendado (se houver) e o corpo JSON + headers exatos que foram enviados.
  • Reentrega manual: no detalhe do evento, você pode re-disparar a entrega independentemente do status atual (reusando o mesmo eventId). Use quando o seu endpoint estava fora do ar ou depois de subir uma correção.
A edição de webhooks no Dashboard é restrita a admins/owners, e os headers ficam ocultos em toda a UI por serem material sensível. Para gerenciar headers, use a API de Webhooks.

​
Reconciliação noturna

Mesmo com webhooks, rode um job noturno de reconciliação. Ele cobre o pior caso: a Malvo esgotou as 9 tentativas, ou o seu endpoint ficou fora do ar por mais que a janela de retry de ~3h.
1

Liste os Items ativos

GET /items?clientUserId=... (ou use o seu registro local).
2

Force o sync dos Items defasados

Para cada Item com lastUpdatedAt mais antigo que o esperado, chame PATCH /items/{id} para disparar um novo sync.
3

Re-busque transações dos últimos N dias

Pegue as transações do período recente para capturar qualquer coisa perdida durante uma falha de entrega de webhooks.

Guia de Reconciliação

O passo a passo completo do job noturno e das estratégias de upsert.

​
Próximos passos

Segurança

Headers customizados, IP allowlisting e a tabela de troubleshooting de entrega.

Catálogo de Eventos

Payload e ação recomendada para cada evento.