data.href com o recurso a consultar.
Como assinar
Registre um webhook por tipo de evento, comPOST /webhooks e o nome exato em event. Uma
assinatura event: "all" não recebe eventos financeiros, para não mudar o contrato de quem já
integra. O webhookUrl por Item ou Connect Token também não recebe esses eventos.
Assinar payment_match.confirmed
CONSOLIDATED_INTELLIGENCE_ENABLED e uma versão de
cálculo ativa). A entrega usa o mesmo mecanismo dos demais webhooks: reentrega com backoff
(Entrega e retentativas) e assinatura HMAC no header Malvo-Signature
(Segurança).
Envelope
Os eventos financeiros usam um envelope próprio, emsnake_case:
Envelope
Idempotência e ordem
- Guarde o
event_ide ignore repetições. O mesmo fato nunca gera doisevent_id. - A ordem global não é garantida. Dois eventos do mesmo alerta podem chegar fora de ordem.
Compare
data.version(alertas e correspondências) com a última versão que você processou e descarte a mais antiga. - Na dúvida, busque o estado atual em
data.href. O evento publicado fica 30 dias na fila de saída; o estado atual continua na API. - Valores de título e de correspondência não vêm nos eventos
payment_match.*. Busque-os na API.
Eventos do perfil
financial_profile.analysis_completed
Um cálculo novo foi publicado. data.request_id é o analysis_id devolvido por
POST /financial-profiles/{id}/analyses; data.analysis_id é o cálculo publicado.
financial_profile.analysis_completed
trigger inclui os gatilhos da F2: profile_sync_cycle (ciclo de sincronização do perfil),
obligation_import (carga recebida ou ativada), obligation_source_activity (atividade confirmada
ou perdida) e payment_match (decisão ou reavaliação da conciliação).
financial_profile.analysis_failed
O pedido de cálculo falhou. failure_reason: no_eligible_source, input_error,
calculation_error, publish_error ou lease_exhausted.
financial_profile.analysis_failed
financial_profile.quality_changed
Os motivos de qualidade do perfil mudaram. status é sufficient sem motivos e insufficient com
algum. É estado de qualidade dos dados, não deterioração financeira. O primeiro registro de
qualidade do perfil não gera evento; só as mudanças seguintes.
financial_profile.quality_changed
financial_profile.bank_position_updated
Um ciclo de sincronização do perfil fechou (FR-036). Você pode responder com uma fotografia nova dos
títulos daquele perfil para alinhar as duas fontes. A resposta é opcional e não muda os prazos da
cadência. O evento traz só
ids, horários e a defasagem, nunca saldo.
financial_profile.bank_position_updated
close_reason é all_accounts (todas as contas BANK receberam saldo depois do horário) ou
timeout (90 minutos). As posições são o updateDateTime do saldo da API Contas. Este evento não
traz href: consulte GET /financial-profiles/{id}/sync-schedule.
financial_profile.forecast_updated pertence à F3 e ainda não é emitido.
Eventos de alerta
financial_alert.opened, financial_alert.updated, financial_alert.resolved e
financial_alert.retracted seguem o ciclo de vida dos alertas.
data traz o alerta na versão notificada:
financial_alert.opened
alert_id.
financial_alert.retracted
Revogação da fonte
Quando uma fonte usada pelo alerta perde autorização, cada alerta ativo que depende dela publicafinancial_alert.retracted com reason: "source_revoked". O evento não traz conteúdo da fonte:
sem severity e sem window, com analysis_id: null no envelope, condition.reasons igual a
["source_not_authorized"], condition.measures igual a {}, condition.evidence igual a [] e
condition.basis com bank_position_at e source_as_of nulos. retracts aponta a versão anterior,
como em qualquer retratação.
financial_alert.retracted (fonte revogada)
- Eventos de alerta ainda não entregues que carregam conteúdo da fonte revogada são suprimidos: os
que ainda não entraram na fila de saída são apagados e as entregas pendentes não são enviadas. Só o
evento
source_revokedsegue. - Antes de cada envio a Malvo confere de novo a entrega. Uma entrega reivindicada antes da revogação não é enviada, e uma cópia já reivindicada cuja linha na fila de saída foi apagada ou finalizada é descartada.
- Ao ler o alerta,
source_authorizationvemunauthorizede o conteúdo fica bloqueado, inclusive nas versões antigas do histórico. Veja Fonte sem autorização.
source_revoked, apague o que guardou das versões anteriores do alerta. Um evento antigo
que chegue depois tem version menor e deve ser descartado.
Eventos de conciliação
data traz payment_match_id, state, version, obligation_id, transaction_id,
occurred_at, href e, quando houver, absorption_basis e review_reason. Sem valores.
payment_match.confirmed
T-1001 traz o payment_match_id e a Malvo publica a absorção:
payment_match.source_acknowledged
absorption_basis é explicit_reference (a liquidação trouxe o payment_match_id),
inferred_exact (redução exata, sem outra mudança) ou manual_review (decisão de um revisor).
A absorção inferida pode ser desfeita por revisão; nesse caso chega payment_match.review_required
com review_reason: "absorption_reversed".
Fontes
- PRD v1.3, seção 14, “Eventos propostos” e seção 11 (FR-020, FR-021 e FR-031): identidade estável, reentrega com idempotência no consumidor, sem ordem global, retratação vinculada ao alerta original.
- Lei nº 13.709/2018 (LGPD), art. 6º, 15 e 16, e a política de retenção da Malvo (§4.1, §4.3 e §7): revogação encerra o tratamento e bloqueia o conteúdo da fonte nos alertas e nos eventos.
- API Contas do Open Finance Brasil 2.5.1 (
AccountBalancesData.updateDateTime), lida em 12/10/2026: posição bancária usada emfinancial_profile.bank_position_updated.