Webhook
Nesta seção, você encontrará informações sobre o funcionamento do Webhook do produto Unico IDPay
Os artigos GetProcess desta documentação descrevem uma maneira de obter o status de um processo através de uma chamada a um endpoint. Dessa forma, é realizado um polling para receber informações sobre os processos criados. Isso significa que o endpoint pode ser chamado diversas vezes para um mesmo processo para se obter o status mais recente.
Com o uso de webhooks é possível notificar um endpoint específico toda vez que o status de um processo for alterado.
O que é um webhook?
Webhook é um serviço de notificação sistêmica que permite a integração assíncrona entre sistemas, onde um sistema notifica o outro através de um gatilho. Assim, os webhooks podem manter sistemas atualizados com informações mais recentes sem ser necessária a verificação constante por atualizações através de polling.
Como configurar o Webhook
Para configurar o webhook, são necessárias as seguintes informações:
URL de notificação: É o endpoint usado pelo By Unico para as notificações sobre as atualizações de status.
Tipo de autenticação: É o método de autenticação usado para invocar o endpoint. As seguintes opções estão disponíveis:
Basic Authorization;
API Key;
Sem autenticação.
Secret: Indica um segredo usado para a autenticação. O secret só é necessário quando o tipo de autenticação for Basic Authorization e API Key:
Para o Basic Authentication é preciso enviar no formato
user:pass.Para API Key, é possível enviar em dois formatos:
header:value, quando é desejado que o header tenha um nome específico;value: quando o header desejado é o Authorization
Configurações de retentativas: Indica o número de tentativas para o caso de falha na chamada ao endpoint:
Número máximo de tentativas;
Intervalo entre tentativas (em segundos);
Rate limit: Limite máximo de envios simultâneos (máximo: 500);
Timeout: Tempo máximo de espera para a resposta do endpoint (em segundos).
Status a serem notificados: É possível se inscrever em status específicos para receber as notificações. São eles:
approved: Transação aprovada;processing: Transação em processamento;inconclusive: Não conseguimos realizar uma validação conclusiva;shared: Transação compartilhada, aguardando envio;skiped: A pessoa pulou a captura biométrica no fluxo;unknown-share: A pessoa marcou que não reconhece aquela compra;absent-holder: O titular do cartão não está presente para realizar a captura;expired: A pessoa não realizou a captura dentro do tempo estabelecido e a transação foi expirada.
Sobre a autenticação:
A API pode ser protegida por um método de autenticação como Basic Authentication ou API Key. Uma lista de IPs válidos para acesso também pode ser definida para proteção complementar.
Integração com o IDPay
Ao configurar um webhook na plataforma, você pode obter informações sobre os processos através de notificações enviadas para um endpoint da API desenvolvida por você para receber essas atualizações.
As informações enviadas pela plataforma para a API são:
ID: ID da transação;status: Status da transação;
Note que é possível escolher os status que o cliente deseja ser notificado, através da configuração do webhook. Após o envio dessas informações, a resposta esperada deverá ser síncrona.
Requisições
A requisição deve ser um método POST em uma API REST tornando mais fácil e seguro o envio das informações. Todos os campos devem ser obrigatórios. O corpo da requisição deve aceitar o ID da transação e o estado, como mostrado no exemplo a seguir:
Resposta
A resposta deve vir de forma síncrona. O status para requisições bem sucedidas deverá estar no intervalo de 200 a 299. Qualquer outro status será considerado como falha e o IDPay irá realizar novas tentativas de notificações (com exponential backoff entre elas), até receber uma resposta 2xx ou até atingir o número máximo de tentativas.
Status da Resposta
Atualmente temos um conjunto de status, porém esse conjunto pode variar no futuro. Então é recomendado deixar configurável os status que o cliente tem interesse para tomar alguma ação. Por exemplo, se há o desejo de tomar uma ação toda vez que uma captura é realizada com sucesso, atualmente isso ocorre com o status processing, porém como isso pode ser modificado no futuro, é recomendado que o status que indica que a captura foi realizada com sucesso seja uma configuração no sistema, de modo que uma alteração no futuro para o status de captured seja facilmente realizada.
Além disso, recomendamos ter ações específicas para status específicos, e uma ação geral caso o status não seja reconhecido (por exemplo assumir que tudo que for diferente de processing e approved é inconclusivo). isso é importante, pois novos status podem surgir no futuro e não é esperado que o webhook quebre em função disso.
Considerações importantes
Atente-se aos seguintes aspectos ao desenvolver API que o IDPay irá utilizar para notificar as mudanças de status:
Dúvidas?
Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.
Last updated