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. Também pode ser definido no Dashboard pelo Proprietário da aplicação, que mostra os nomes dos cabeçalhos, mas nunca seus valores. Para provar que uma entrega veio da Pluggy inalterada, use a assinatura. |
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 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. |
clientId | O ID do Cliente da aplicação a 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 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 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.
Quando a aplicação tem um secret de assinatura, cada entrega carrega X-Pluggy-Signature — veja Segurança do Webhook.
Leia o guia: Webhook — exemplos de payload por evento e solução de problemas.
