Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs

Webhook

Assinando eventos, a lista de eventos, a carga útil que cada notificação carrega e as regras de entrega e reenvio.

Ver como Markdown

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 um url e um event. Entrega esse evento para cada recurso da aplicação.
  • webhookUrl em 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#

CampoObrigatórioSignificado
urlsimUma URL HTTPS pública — veja requisitos de URL. localhost não é aceito — use um túnel como ngrok durante o desenvolvimento.
eventsimUm 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.
headersnãoEnviado 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:

RegraExemplo rejeitado
Apenas HTTPShttp://example.com/pluggy
Apenas porta HTTPS padrão (443)https://example.com:8443/pluggy
Sem nome de usuário ou senha na URLhttps://user:pass@example.com/pluggy
O host é um nome de domínio, não um endereço IPhttps://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úblicosum 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

EventoDispara quando
item/createdUm Item foi criado e conectado com sucesso.
item/updatedUm Item foi atualizado e sincronizado com sucesso.
item/deletedUm Item foi excluído.
item/errorUma execução terminou em erro; USER_AUTHORIZATION_PENDING também dispara isso.
item/waiting_user_inputO Item precisa de entrada do usuário (MFA) para continuar.
item/waiting_user_actionO Item precisa que o usuário atue em seu dispositivo — autorize no aplicativo do banco, escaneie um código QR.
item/login_succeededO login na instituição foi bem-sucedido; a coleta de dados está em andamento.
connector/status_updatedUm conector mudou de status (ONLINE, UNSTABLE, OFFLINE). Transporta connectorId.
transactions/createdNovas transações após uma atualização; transporta createdTransactionsLink para buscá-las.
transactions/updatedTransações mudaram após uma atualização; transporta seus ids.
transactions/deletedTransaçõ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

EventoDispara quando
payment_intent/createdUma intenção de pagamento foi criada para uma solicitação.
payment_intent/waiting_payer_authorizationA intenção precisa da autorização do pagador.
payment_intent/completedA intenção foi concluída.
payment_intent/errorA intenção falhou.
payment_request/updatedUma solicitação de pagamento mudou de status.
scheduled_payment/created, /completed, /error, /canceledUm pagamento agendado de uma autorização foi movido.
scheduled_payment/all_created, /all_completedCada pagamento agendado de uma autorização foi criado / concluído.
automatic_pix_payment/created, /completed, /error, /canceledUm pagamento de uma solicitação de PIX Automático foi movido.
smart_transfer_preauthorization/completed, /errorUma pré-autorização de Transferência Inteligente foi aprovada ou falhou.
smart_transfer_payment/completed, /errorUm pagamento de Transferência Inteligente foi liquidado ou falhou.

Payload#

Cada notificação carrega:

CampoSignificado
eventO nome do evento.
eventIdIdentifica o evento; o mesmo valor quando um evento é entregue a várias URLs.
clientIdO ID do Cliente da aplicação a qual o webhook pertence. Ignore uma notificação cujo clientId não seja seu.
triggeredByUSER (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 entidadeitemId em eventos de Item, transactionIds em eventos de transação, connectorId em eventos de conector, e assim por diante por evento.
clientUserIdSomente 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.

Esta página foi útil?