Webhooks

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:

  • 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:

  • Enviar header:value, quando é desejado que o header tenha um nome específico;

  • Enviar somente o 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. Veja abaixo os status que são notificados para cada tipo de integração:

  • finished: Processo finalizado.

Integração com a plataforma Unico IDCloud

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;

• lastEvent: Último evento disparado (somente retornamos este parâmetro caso o processo seja expirado);

• lastEventDescription: Descrição do último evento disparado (somente retornamos este parâmetro caso o processo seja expirado).

Clique aqui para conferir o enum dos eventos que podem ser retornados no webhook

LastEvent	Description
EVENT_TYPE_PROCESS_CREATED	Processo criado
EVENT_TYPE_QR_CODE_READ	QRCode foi lido
EVENT_TYPE_PROCESS_STARTED_BY_USER	Processo iniciado pelo usuário
EVENT_TYPE_IDENTITY_VALIDATION_STEP_FINISHED	Usuário realizou etapa de validação
EVENT_TYPE_DOCUMENT_STEP_STARTED	Etapa de documento foi iniciada
EVENT_TYPE_DOCUMENT_PHOTO_CAPTURED	Foto do documento foi capturada
EVENT_TYPE_DOCUMENT_UPLOADED_FROM_GALLERY	Foi feito upload do documento
EVENT_TYPE_DOCUMENT_STEP_FINISHED	Etapa do documento foi finalizada
EVENT_TYPE_SIGNATURE_STEP_STARTED	Etapa de assinatura foi iniciada
EVENT_TYPE_DOCUMENT_FOR_SIGNATURE_ACCEPTED	Etapa de assinatura do documento foi aceita
EVENT_TYPE_ENVELOPE_OPENED_FOR_SIGNATURE	Envelope foi aberto para assinatura
EVENT_TYPE_DOCUMENT_FOR_SIGNATURE_VIEWED	Documento para assinatura foi visualizado
EVENT_TYPE_DOCUMENT_FOR_SIGNATURE_SIGNED	Documento foi assinado
EVENT_TYPE_SIGNATURE_STEP_FINISHED	Etapa de assinatura do documento foi finalizada
EVENT_TYPE_SESSION_ENDED	Sessão encerrada por tempo limite ou por nova sessão criada
EVENT_TYPE_ERROR_ON_DOCUMENT_STEP	Erro na etapa do documento
EVENT_TYPE_ERROR_ON_SIGNATURE_STEP	Erro na etapa da assinatura

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:

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id",
  "lastEvent":"EVENT_TYPE_PROCESS_CREATED",
  "lastEventDescription":"Process created"
}

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.

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 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.

Pontos de atenção

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. A consulta ao endpoint está descrita nas seções de GetProcess respectivas a cada meio de integração.

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.

Rate limit

Com intuito de 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.