Webhook é uma funcionalidade de retorno assíncrono de chamadas baseadas no protocolo HTTP que permite comunicação leve e orientada a eventos entre 2 interfaces de programação de aplicativos (APIs). O Webhook pode ser usado para diminuir custos operacionais entre as instituições participantes possibilitando um pooling otimizado para obter informações dos recursos e podem ser usados para acionar fluxos de trabalho de automações internas das instituições.
A instituição (detentora de contas e/ou transmissora de dados) envia uma notificação à iniciadora de pagamento e/ou receptora de dados informando que ocorreu uma mudança no estado do recurso e ela deverá consultar o recurso para obter mais informações.
A especificação do Webhook será versionada de forma desacoplada da especificação da API de Pagamentos, conforme instruções abaixo, com o objetivo de possibilitar o reaproveitamento da especificação quando o Webhook for adotado para outras APIs do ecossistema
Para a iniciadora de pagamentos comunicar às detentoras de conta de que está preparada para receber notificações do Webhook, será preciso cadastrar no diretório o prefixo da sua URL de notificações conforme o padrão abaixo:
/open-banking/webhook/[Versão do Webhook]
A iniciadora de pagamentos deverá ter os seguintes endpoints, quando habilitar a funcionalidade de Webhook para a API de Pagamentos:
/payments/[Versão da API]/consents/{consentId}
/payments/[Versão da API]/pix/payments/{paymentId}
Versionamento do Webhook: Ocorrerá de forma desacoplada de qualquer API presente no ecossistema. Tal decisão tem por objetivo possibilitar o reaproveitamento da especificação quando o Webhook for adotado para outras APIs no ecossistema do Open Finance Brasil, sendo assim:
A versão do Webhook fará parte da URL base do serviço:
<host>/open-banking/webhook/[Versão do Webhook]
O restante da URL deverá conter o nome da API, sua versão, e qual endpoint dentro da API que este Webhook notificará:
/[nome_da_API]/[Versão_da_API]/[endpoint_da_API]
Utilizando a API de Iniciação de Pagamentos como exemplo, ficaria da seguinte forma:
/payments/[Versão_da_API]/consents/{consentId}
/payments/[Versão_da_API]/pix/payments/{paymentId}
Prazo para sincronização: As detentoras de conta e transmissoras de dados devem sincronizar o seu mecanismo de notificações por Webhook com o fluxo DCR/DCM de modo que as notificações para as iniciadoras de pagamento e receptoras de dados se iniciem em até 10 minutos após a execução do DCR/DCM.