Webhook
Nesta seção, você encontrará informações sobre o funcionamento do Webhook da plataforma Unico IDCloud
Atualizado
Isto foi útil?
Portuguese (Brazil)
Nesta seção, você encontrará informações sobre o funcionamento do Webhook da plataforma Unico IDCloud
Atualizado
Isto foi útil?
Os artigos GetProcess respectivos aos meios de integraçã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.
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.
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:
OAuth2;
Basic Authorization;
API Key;
Sem autenticação.
Para OAuth2 é necessário enviar as seguintes informações:
Endpoint do webhook;
URL do provedor OAuth2;
ClientId do provedor OAuth2;
Secret do provedor OAuth2.
Para o Basic Authorization é 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: Atualmente a notificação é enviada sempre que o estado de um processo for alterado para:
finished: Processo finalizado.
2: Em divergência;
3: Concluído;
4: Cancelado;
5: Erro.
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:
processId: ID da transação;
state: Status da transação;
flow: Jornada da transação.
id: ID da transação;
status: Status da transação.
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:
Sobre o status de resposta:
Atualmente a plataforma tem um conjunto de status que pode variar no futuro. Sendo assim, é recomendado que os status que o você tem interesse para tomar alguma ação sejam configuráveis.
A resposta deve vir de forma síncrona. O status para requisições bem sucedidas deve estar no intervalo de 200 a 299. Qualquer outro status é considerado falha e então a plataforma realiza 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.
Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da .