Eventos
Lista de eventos enviados ao seu webhook quando itens e transações mudam de estado.
Quando você cadastra um webhook, a API envia notificações POST para a sua URL sempre que ocorrem os eventos abaixo. Para o fluxo exato de como receber e validar essas requisições, veja Como receber webhooks.
Formato comum de cada notificação
Todas as notificações são enviadas com:
- Método: POST
- Header
Content-Type: application/json - Header
Authorization: o valor dosecretque você configurou no webhook (use para validar a origem) - Body: objeto JSON com
eventedata:
{
"event": "NOME_DO_EVENTO",
"data": { ... }
}Eventos de item (conexão)
Disparados quando o status ou o estado de uma conexão (item) muda.
| Evento | Descrição | Documentação |
|---|---|---|
ITEM_CREATED | Novo item (conexão) criado | ITEM_CREATED |
ITEM_UPDATED | Item atualizado (ex.: status mudou para synced, waiting_user_input) | ITEM_UPDATED |
ITEM_DELETED | Item removido | ITEM_DELETED |
ITEM_ERROR | Erro no processamento do item (ex.: auth_error) | ITEM_ERROR |
ITEM_WAITING_USER_INPUT | Aguardando entrada do usuário (ex.: OAuth) | ITEM_WAITING_USER_INPUT |
ITEM_WAITING_USER_ACTION | Aguardando ação do usuário no app do banco | (payload igual a ITEM_UPDATED: status, itemId) |
ITEM_LOGIN_SUCCEEDED | Login na instituição concluído com sucesso | ITEM_LOGIN_SUCCEEDED |
Esses eventos aparecem ao longo do fluxo de conexão: por exemplo, após criar um item você pode receber ITEM_CREATED e depois ITEM_UPDATED (com status: "waiting_user_input") quando for necessário OAuth, e por fim ITEM_UPDATED ou ITEM_LOGIN_SUCCEEDED com status: "synced".
Eventos de transações
Disparados quando há novas transações ou atualização de transações existentes em uma conta.
| Evento | Descrição | Documentação |
|---|---|---|
TRANSACTIONS_CREATED | Novas transações criadas na conta | TRANSACTIONS_CREATED |
TRANSACTIONS_UPDATED | Transações existentes atualizadas | TRANSACTIONS_UPDATED |
Ordem recomendada na documentação
- Como receber webhooks — fluxo completo (cadastro, validação, retentativas).
- Gerenciar webhooks — endpoints para criar, listar, atualizar e remover webhooks.
- Esta página e as páginas de cada evento — referência dos payloads.