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 ou um Connect Token. Entrega cada evento, mas apenas para esse recurso (ou os Itens criados com esse token).
Recurso Webhook#
| Campo | Obrigatório | Significado |
|---|---|---|
url | sim | Uma URL HTTPS pública — veja requisitos de URL. localhost não é aceito — use um túnel como ngrok durante o desenvolvimento. |
event | sim | Um evento das tabelas abaixo, ou all para tudo. Não há curinga por produto: para receber todos os eventos de Item, registre all ou um webhook por evento. |
headers | não | Enviado com cada entrega para esta URL — a maneira de passar um secret que seu endpoint verifica. Apenas configurável através da API, nunca mostrado no dashboard. |
Endpoints: GET /webhooksAPI, POST /webhooksAPI, e recuperar, atualizar e excluir em /webhooks/{id}API.
Requisitos de URL#
A url de um webhook — e o webhookUrl de um Item ou um Connect Token — deve ser um endpoint HTTPS público:
| Regra | Exemplo rejeitado |
|---|---|
| Apenas HTTPS | http://example.com/pluggy |
| Apenas porta HTTPS padrão (443) | https://example.com:8443/pluggy |
| Sem nome de usuário ou senha na URL | https://user:pass@example.com/pluggy |
| O host é um nome de domínio, não um endereço IP | https://203.0.113.10/pluggy |
Sem localhost ou nomes internos (.local, .internal, .localdomain, .home.arpa) | https://api.internal/pluggy |
| O domínio resolve apenas para endereços IP públicos | um domínio que resolve para 10.0.0.5 |
| No máximo 2048 caracteres | — |
Túneis e serviços de inspeção de requisições como ngrok ou webhook.site são aceitos.
Uma URL que quebra uma regra falha com 400, e a mensagem nomeia a regra:
Note
Webhooks registrados antes de uma regra existir continuam recebendo eventos, mas você não pode atualizar ou reabilitar um até que sua url siga todas as regras.
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 excluído. |
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 — autorize no aplicativo do banco, escaneie 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 mudou; 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 PIX Automática 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. |
clientId | O ID do Cliente da aplicação à qual o webhook pertence. Ignore uma notificação cujo clientId não seja seu. |
triggeredBy | USER (um Connect Token, por exemplo, o widget), CLIENT (uma Chave da 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 esses para seu usuário através de itemId. |
Entrega e tentativas#
Uma entrega é bem-sucedida quando seu endpoint responde 2xx dentro de 10 segundos. Responda primeiro, processe depois — um manipulador lento é contado como uma falha e tentado novamente.
Em caso de falha: até 3 tentativas no total — imediatamente, ~15 minutos após a primeira falha, e então ~2 horas após a segunda. Depois disso, o evento é descartado. Status 400, 401, 403, 404 e 405 nunca são tentados novamente. Exceção: item/login_succeeded e item/waiting_user_input recebem suas 3 tentativas ~6 minutos de intervalo, nunca a espera de 2 horas.
Redirecionamentos não são seguidos: um 3xx conta como uma falha. Se o domínio resolver para um endereço IP privado ou reservado quando a notificação for enviada, não será entregue e não será tentado novamente.
Leia o guia: Webhook — exemplos de payload por evento e solução de problemas.