Toda entrega é um corpo JSON que compartilha um envelope comum e, por cima dele, adiciona identificadores específicos do recurso. Esta página lista cada evento que a Malvo dispara, com um payload de exemplo e a ação recomendada.

​
Envelope comum

Semântica de triggeredBy: USER = ação do usuário final (widget), CLIENT = chamada à sua API, SYNC = motor de sincronização automática da Malvo, INTERNAL = operação interna/admin da Malvo.

​
Eventos disparados

Dispara quando um Item é criado com sucesso (conexão inicial concluída).
Ação recomendada: GET /items/{itemId} para ler o estado completo, depois GET /accounts?itemId=....
Dispara quando um Item termina uma rodada de sync e os dados válidos coletados já foram persistidos na Malvo, tanto em SUCCESS quanto em PARTIAL_SUCCESS. Em uma conclusão parcial, consulte executionStatus e statusDetail para identificar as famílias incompletas; uma tentativa posterior que completar a importação dispara um novo item/updated. Eventos transactions/* representam somente deltas que já foram persistidos.
Ação recomendada: puxe GET /items/{id}, verifique executionStatus/statusDetail e depois atualize contas, transações e investimentos disponíveis.
Dispara quando o Item termina em erro (erro de login, MFA inválido, USER_AUTHORIZATION_PENDING, etc.). Carrega um objeto error.
Campos de error: code (string enum) e message (humanamente legível).Ação recomendada: apresente o erro ao usuário; se recuperável, leve-o pelo modo de atualização do Connect Widget com aquele itemId.
Dispara quando o conector exige MFA, OTP ou captcha.
Ação recomendada: abra o widget em modo de atualização para o usuário inserir o parâmetro que falta.
Dispara quando o provedor exige que o usuário conclua uma ação fora da Malvo, como confirmar o consentimento no aplicativo ou site do banco.
userAction.instructions explica o próximo passo e userAction.attributes carrega metadados adicionais do provedor quando existirem.Ação recomendada: mantenha o fluxo aberto, mostre as instruções ao usuário e aguarde item/login_succeeded, item/updated ou item/error.
Dica transitória de que a autenticação no provedor deu certo — o sync ainda está rodando. Útil para UX (“conectado, buscando dados…”).Regra especial de entrega: entregue no máximo 3 vezes, sem backoff por hora. Veja Entrega & Retry.
Ação recomendada: apenas UX. Não trate como conclusão do sync — espere o item/updated.
Dispara quando o Item é deletado (via seu DELETE /items/{id}, revogação de consentimento ou ação de admin).
Ação recomendada: faça cascade-delete ou marque como inativo no seu banco.
Dispara quando novas transações são detectadas em uma conta durante um sync.
Ação recomendada: pagine você mesmo GET /transactions?accountId=... e persista (o payload não fornece link nem accountId — use os ids retornados pela paginação).
Transações existentes mudaram (ex.: pendente → liquidada; valor/descrição atualizados pelo banco).
Mesma forma de transactions/created. Ação recomendada: pagine você mesmo GET /transactions?accountId=... e faça upsert pelo id da transação (o payload não fornece link nem accountId).
Dispara quando a sincronização confirma que transações antes persistidas foram canceladas, rejeitadas ou consolidadas durante a reconciliação. Os ids removidos vêm inline para que o consumidor consiga aplicar o mesmo efeito de forma idempotente.
Ação recomendada: remova localmente por transactionIds. Use eventId como chave de idempotência; entregas podem repetir e não têm ordem garantida.
Dispara quando a saúde geral de um conector muda. Enum de status: ONLINE | UNSTABLE | OFFLINE.
Este evento não traz itemId, clientUserId nem triggeredBy. Ação recomendada: pause novas conexões para aquele conector ou avise os usuários afetados.

​
Eventos “never fired” (pagamento)

Para preservar a compatibilidade do protocolo, o registro aceita o enum completo de eventos — incluindo os de iniciação de pagamento. Mas a Malvo faz apenas agregação de dados: os eventos abaixo nunca são emitidos. Registrá-los não causa erro; eles simplesmente nunca disparam.payment_intent/created, payment_intent/waiting_payer_authorization, payment_intent/completed, payment_intent/error, scheduled_payment/created, scheduled_payment/completed, scheduled_payment/error, scheduled_payment/canceled, automatic_pix_payment/created, automatic_pix_payment/completed, automatic_pix_payment/error, automatic_pix_payment/canceled, smart_transfer_preauthorization/completed, smart_transfer_preauthorization/error, smart_transfer_payment/completed, smart_transfer_payment/error, payment_request/updated.

​
Eventos de consentimento

Não há um stream dedicado de consent/*. Mudanças de estado do consentimento aparecem indiretamente:
  • Um consentimento revogado dispara item/error com código USER_AUTHORIZATION_PENDING (ou o Item passa a retornar dados vazios nos GET seguintes).
  • Após re-autorização pelo modo de atualização do widget, você recebe item/updated e o consentExpiresAt (no objeto Consent) é renovado.
  • O estado vivo do consentimento é sempre consultável via GET /consents?itemId={id}.

​
Próximos passos

Entrega & Retry

Como cada um desses eventos é entregue, reentregue e deduplicado.

Segurança

Como validar que um payload realmente veio da Malvo.