Obter resultado da transação via webhook

O artigo Get Process descreve a maneira de obter o status da transação através da 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 a necessidade de 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 IDUnico 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: Atualmente a notificação é enviada sempre que o estado de um processo for alterado para:
  • 2: Em divergência;
  • 3: Concluído;
  • 4: Cancelado;
  • 5: Erro.

Integração com o IDUnico

Ao configurar um webhook, 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 para a API são:

• id: ID da transação;
• status: status da transação;

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.

Requisiçã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 status, como mostrado no exemplo a seguir:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": 3
}

Resposta

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 novas tentativas de notificações (com exponential backoff entre elas) são realizadas até receber uma resposta 2xx ou até atingir o número máximo de tentativas.

Status da Resposta

O status da transação pode variar no futuro. Sendo assim, é recomendado que o status que você tem interesse para tomar alguma ação seja configurável.

Rate Limit

Para não sobrecarregar seus recursos em situações de muitas transações, é possível especificar um limite superior de vezes em que o endpoint pode ser invocado.

Taxa de erros

A taxa de erros (respostas fora do intervalo de [200, 299]) deve ser sempre baixa. Caso contrário, o throughput do webhook será automaticamente reduzido, e essa redução junto ao mecanismo do retry pode implicar no aumento do tempo de execução de novos webhooks.

Idempotência

A atual implementação de webhook possui a garantia de at-least once delivery, portanto o mesmo status pode ser notificado mais de uma vez. Sendo assim, a implementação do endpoint deve ser feita de maneira idempotente.

Fallback

Em caso de alguma indisponibilidade no serviço do webhook, é recomendado que exista um método de fallback para que você possa continuar obtendo os status das transações dentro do tempo de resposta estabelecido. É indicado o tempo de 10 segundos na configuração do fallback. A consulta ao endpoint descrita no artigo Get Process pode ser utilizada para esse fim.

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.