Um webhook é uma URL HTTPS sua que recebe um POST com um corpo JSON quando um evento acontece. Duas maneiras de se inscrever:
- Um recurso Webhook —
POST /webhooksAPI com umurle umevent. Entrega esse evento para cada recurso da aplicação. webhookUrlem um recurso — definido ao criar um Item, um Connect Token ou uma Solicitação de Pagamento. Entrega cada evento, mas apenas para esse recurso (ou os Items criados com esse token).
Recurso Webhook#
| Campo | Obrigatório | Significado |
|---|---|---|
url | sim | Apenas HTTPS. localhost não é aceito — use um túnel como ngrok enquanto desenvolve. |
event | sim | Um evento das tabelas abaixo, item/all para cada evento de Item, ou all para tudo. |
headers | não | Enviado com cada entrega para esta URL — a maneira de passar uma chave de API que seu endpoint requer. Apenas configurável através da API, nunca mostrado no dashboard. |
Endpoints: GET /webhooksAPI, POST /webhooksAPI, e recuperar, atualizar e deletar em /webhooks/{id}API.
Eventos#
Dados
| Evento | Dispara quando |
|---|---|
item/created | Um Item foi criado e conectado com sucesso. |
item/updated | Um Item foi atualizado e sincronizado com sucesso. |
item/deleted | Um Item foi deletado. |
item/error | Uma execução terminou em erro; USER_AUTHORIZATION_PENDING também dispara isso. |
item/waiting_user_input | O Item precisa de entrada do usuário (MFA) para continuar. |
item/waiting_user_action | O Item precisa que o usuário atue em seu dispositivo — autorizar no aplicativo do banco, escanear um código QR. |
item/login_succeeded | O login na instituição foi bem-sucedido; a coleta de dados está em andamento. |
connector/status_updated | Um conector mudou de status (ONLINE, UNSTABLE, OFFLINE). Transporta connectorId. |
transactions/created | Novas transações após uma atualização; transporta createdTransactionsLink para buscá-las. |
transactions/updated | Transações mudaram após uma atualização; transporta seus ids. |
transactions/deleted | Transações removidas após uma atualização; transporta seus ids. |
Eventos de transação disparam apenas quando algo muda; uma atualização sem novas transações não emite transactions/created.
Pagamentos
| Evento | Dispara quando |
|---|---|
payment_intent/created | Uma intenção de pagamento foi criada para uma solicitação. |
payment_intent/waiting_payer_authorization | A intenção precisa da autorização do pagador. |
payment_intent/completed | A intenção foi concluída. |
payment_intent/error | A intenção falhou. |
payment_request/updated | Uma solicitação de pagamento mudou de status. |
scheduled_payment/created, /completed, /error, /canceled | Um pagamento agendado de uma autorização foi movido. |
scheduled_payment/all_created, /all_completed | Cada pagamento agendado de uma autorização foi criado / concluído. |
automatic_pix_payment/created, /completed, /error, /canceled | Um pagamento de uma solicitação de PIX Automático foi movido. |
smart_transfer_preauthorization/completed, /error | Uma pré-autorização de Transferência Inteligente foi aprovada ou falhou. |
smart_transfer_payment/completed, /error | Um pagamento de Transferência Inteligente foi liquidado ou falhou. |
Payload#
Cada notificação carrega:
| Campo | Significado |
|---|---|
event | O nome do evento. |
eventId | Identifica o evento; o mesmo valor quando um evento é entregue a várias URLs. |
triggeredBy | USER (um Connect Token, por exemplo, o widget), CLIENT (uma Chave de API, por exemplo, um PATCH), SYNC (auto-sync) ou INTERNAL (suporte Pluggy). Ausente em item/deleted, connector/status_updated e transactions/deleted. |
| o id da entidade | itemId em eventos de Item, transactionIds em eventos de transação, connectorId em eventos de conector, e assim por diante por evento. |
clientUserId | Somente em eventos item/* — o valor definido através das options do Connect Token. Não em transactions/*: mapeie-os para seu usuário através de itemId. |
Entrega e tentativas#
Uma entrega é bem-sucedida quando seu endpoint responde 2xx dentro de 5 segundos. Responda primeiro, processe depois — um manipulador lento é contado como uma falha e tentado novamente.
Em caso de falha: três tentativas consecutivas; se todas falharem, mais três após 1 hora; se essas falharem, uma última tentativa de três após 2 horas. Até 9 entregas de um evento. Exceção: item/login_succeeded recebe apenas as três tentativas consecutivas, sem tentativas atrasadas.
Leia o guia: Webhook — exemplos de payload por evento e solução de problemas.