Evento organization.updated
Disparado para a organização da plataforma quando uma organização conectada muda
em um campo público relevante. Isso inclui status de ativação financeira, a
lista de tarefas da ativação (requirements), conta para saques ativa,
dados cadastrais, endereço de cobrança, marca (branding_settings) e metadata
da relação com a plataforma. Também dispara quando o plano de taxas
da organização muda (fee_plan). Trocar o plano padrão da plataforma não gera
este evento: as organizações já criadas mantêm o plano que tinham.
O evento também dispara quando apenas o motivo muda: se a organização já
estava disabled e a análise adiciona ou refina uma pendência, chega um novo
organization.updated com previous_attributes.requirements — mesmo com
activation_status inalterado.
Quando os pagamentos são bloqueados, data.object.requirements.disabled_reason
passa a blocked.payments. Quando o acesso da conta é bloqueado, o valor passa
a blocked.account. Se o bloqueio voltar ao nível de pagamentos, o valor volta
a blocked.payments. A liberação completa devolve o motivo vigente do
cadastro financeiro ou null. Cada transição inclui o requirements anterior
em data.previous_attributes. O cadastro financeiro determina
activation_status.
data.object carrega o estado atual completo da organização conectada (incluindo
activation_status e payout_account quando preenchidos), e
data.previous_attributes mostra o valor anterior dos campos que mudaram —
útil pra detectar transições. Quando requirements muda, o diff traz o
objeto anterior completo.
Use este evento para sincronizar o admin da plataforma sem precisar buscar a
organização novamente. Quando a conta para saques ativa muda,
data.object.payout_account traz a conta atual e
data.previous_attributes.payout_account traz a conta anterior.
O payload em
data.object é sempre o estado completo e atual. Use
data.previous_attributes apenas para saber o que mudou; a fonte do estado
final é data.object.Quando acontece
Como processar
- Registre o
iddo evento (evt_*) para processar o webhook de forma idempotente. - Use
data.object.id(org_*) para atualizar o registro local da organização conectada. - Aplique o estado completo de
data.object; não reconstrua estado final apenas pelo diff. - Use
data.previous_attributespara auditoria, notificações e regras condicionais de transição. - Libere recebimentos quando
activation_statusestiveractive; bloqueie quando estiverdisabled. - Em
not_submittedapós um envio, leiarequirements.errors, corrija os caminhos demissinge chame/submitnovamente na mesma organização. - Em
disabled, decida pelorequirements: sedisabled_reasonviernull, corrija os caminhos emmissinge inicie outra tentativa na mesma organização — outra activation session no hospedado, ou atualização +/submitpela API. Sedisabled_reasonvier preenchido, o caso é terminal: encaminhe ao suporte e não repita automaticamente."under_review"indica conta já aprovada que foi suspensa depois, por segurança, sem nada a corrigir. - Exiba
message/resolutionde cada erro como estão (inglês) ou traduza a partir docode; tratecodedesconhecido de forma genérica. - Atualize a conta exibida no admin usando somente os dados públicos de
payout_account, comoaccount_number_last4. - Trate ausência de uma chave em
previous_attributescomo “campo não mudou”.
Campos importantes
Status financeiros
Exemplo: plano de taxas mudou
A plataforma trocou o plano de uma organização do padrão (plan_nVTh3XtU, com a
tabela de juros 00349) para plan_k6F3mqMZ, que usa a tabela 00299. A
tabela vem com o plano, então o diff carrega os dois campos:
Exemplo: marca mudou
A plataforma trocou a aparência de uma organização filha comPOST /v1/organizations/{id}: o
botão passou do índigo do catálogo para o verde #278629 da marca, o painel do
produto ganhou o fundo #F6F9FC e o estilo passou de ellipse para squircle. O
diff traz o bloco branding_settings anterior completo, não só as chaves que
mudaram:
appearance: null),
previous_attributes.branding_settings traz o bloco que ela tinha. O caminho
inverso também aparece: uma organização que seguia a plataforma e ganhou
aparência própria chega com previous_attributes.branding_settings igual a
{ "appearance": null }. Mudar a aparência da própria plataforma não gera este
evento nas organizações filhas que a seguem: o que elas salvaram continua
appearance: null.
Exemplo: envio falhou antes da análise
Quando uma submissão feita pela API falha antes de entrar na análise, o evento informa a volta paranot_submitted e mantém o motivo acionável no objeto atual:
Exemplo: cadastro aprovado
previous_attributes.requirements traz o objeto anterior completo — durante a
análise, pending_verification listava o que estava sendo verificado. Ausência
de uma chave no diff significa “campo não mudou”.
Exemplo: cadastro reprovado
disabled_reason: null indica que há caminho de correção: os caminhos em
missing dizem o que recoletar. Depois, inicie outra tentativa na mesma
organização pelo canal da integração — outra activation session no hospedado,
ou atualização + /submit pela API.
Exemplo: motivo mudou, status não
Quando a análise adiciona ou refina uma pendência de uma organização que já estavadisabled, o diff carrega apenas requirements:

