HomeGuia de ProdutoCertiface APIReleases

Webhook

Receba notificações da jornada do usuário

📘

Você sabia?

Um Webhook é um mecanismo que permite que uma API envie notificações em tempo real para outras aplicações quando eventos específicos ocorrem.

Em vez de uma aplicação solicitar repetidamente informações da API em intervalos regulares (pooling), o Webhook inverte esse fluxo de comunicação, permitindo que a API envie os dados automaticamente para uma URL específica configurada pela aplicação.

Dessa forma, sempre que um evento ocorrer na Certiface API, como uma atualização de status ou criação de um novo recurso, a informação é enviada diretamente para a aplicação por meio do Webhook. Isso torna o processo mais eficiente, reduzindo a necessidade de requisições contínuas e fornecendo uma forma mais rápida e direta de receber informações atualizadas em tempo real.

Bom saber: além disso, as requisições contínuas podem causar um bloqueio no firewall da Oiti, impedindo que as informações cheguem através da técnica de pooling.

Como a Certiface API usa webhook?

A Certiface API usa webhooks para enviar notificações da Oiti ao cliente.

O cliente configura um endpoint para receber essas notificações, que são enviadas via método POST pela Certiface API, contendo informações sobre a jornada realizada.

O cliente deve compartilhar as informações do endpoint com o time técnico da Oiti, a fim de ter uma integração bem-sucedida.

É possível autenticar o webhook da Certiface API?

Sim, essa configuração aceita diversos tipos de autenticação, incluindo Basic ou OAuth2. Contudo, essa autenticação não é obrigatória.

  • Basic: cliente deve informar usuário e a senha. A Oiti utiliza esses credenciais para retornar webhook autenticado para o cliente;
  • OAuth2: um token dinâmico gerado pelo cliente. É necessário que o cliente forneça um endpoint de autenticação com as credenciais de acesso.
    Assim, a Certiface API enviará uma requisição para este endpoint OAuth2. O cliente deverá retornar um Token, informando o tempo de expiração e o método do token (Bearer, APIKey).
    Ao retornar essas informações para a Certiface API, o webhook é acionado e o token é enviado no (authorization) header.

Como são realizadas as notificações?

As notificações via webhook seguirão as configurações predefinidas, utilizando o protocolo HTTP. Elas são acionadas em casos de tentativas adicionais (retry) ou finalizações (finish) de ações. Os tickets resultantes dessas ações podem ter os seguintes status: RETRY, DONE, ACTIVE ou ERROR.

  • RETRY: caso a transação não seja bem-sucedida, o sistema envia automaticamente uma notificação solicitando uma nova tentativa. Esse status é específico do serviço de Liveness. Para outros serviços o ticket permanece com status ACTIVE.
  • DONE: jornada do usuário finalizado com sucesso;
  • ACTIVE: em situações em que é necessário enviar novos dados biométricos ou documentos durante a mesma jornada do usuário, que exige mais de uma requisição na Certiface API.
  • ERROR: jornada do usuário terminou com erro. Ver documentação Lista de Erros.


💡

Bom saber!

  • Nos status "AWAITING" e “INACTIVE” não são enviadas notificações;
  • Para ação de retry o tempo de envio da notificação pode ser configurável mediante acordo com o time técnico da Oiti. O padrão para retentativas é de três vezes com intervalos de 15 segundos;
  • As notificações serão enviadas em três situações principais: em caso de erro durante a jornada do usuário, na finalização completa da jornada e também na conclusão de serviços específicos, como o envio de biometria facial ou de documentos;
  • Em outros casos, pode resultar do ticket permanecer ativo até que novas retentativas sejam realizadas, tais como: em falhas de assessment em qualquer um dos serviços ou baixa qualidade do documento.

Devo chamar o /result após receber o webhook?

Isso depende dos acordos no ato de configuração junto à equipe técnica da Oiti.
Importante saber que, independente dos casos apresentados abaixo, cabe ao cliente determinar sobre as configurações de autenticação.

Existem dois casos:

  • Caso 1 - Deve chamar o /result : o cliente deve chamar o /result após receber o webhook com as informações resumidas, a fim de conferir os resultados dos serviços executados. Esse é o caso mais comum.

Para este caso as notificações são enviadas em formato json, conforme o conteúdo abaixo:

{
   "service": "RISK_CLASS",
   "status":"DONE",
   "ticket":"00000000000"
}
ObjetoDescrição
serviceNome do serviço que foi finalizado;
statusStatus do ticket (ACTIVE, DONE, AWAITING, INACTIVE, ERROR, RETRY);
ticketTicket da jornada do cliente.

  • Caso 2 - Dispensa chamar o /result: é possível receber todos os resultados via webhook, mas requer configuração prévia pelo time de Delivery da Oiti. Com esta configuração, o webhook terá o mesmo conteúdo do /result, não sendo necessário chamar o endpoint. Devido ao retorno do conteúdo sensível enviado pelo webhook, recomenda-se o uso de autenticação.

Para este caso, as notificações são enviadas em formato json, conforme o exemplo:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "ticket": "00000000-0000-0000-0000-000000000000",
  "externalId": "PRD",
  "ticketStatus": "DONE",
  "reasonInvalidation": {},
  "createAt": "2023-01-26T14:06:57.657Z",
  "updateAt": "2023-01-26T14:08:56.477Z",
  "service": [
    {
      "service": "BUREAU",
      "state": "OK",
      "result": [
        {
          "status": "OK",
          "protocol": "00000",
          "createAt": "2023-01-26T14:08:04.143Z",
          "image": "https://api.dev.certiface.io/result/image/01be78c13-c04de-439c-be24-3ee15886d829/1674742038188"
        }
      ]
    },
    {
      "service": "SERPRO",
      "state": "OK",
      "result": [
        {
          "status": "OK",
          "protocol": "4439",
          "createAt": "2023-01-26T14:08:37.195Z",
          "image": "https://api.dev.certiface.io/result/image/0e78c103-c4de-439c-be24-3ee15886d829/1674742038188"
        }
      ]
    },
    {
      "service": "RISK_CLASS",
      "state": "OK",
      "result": [
        {
          "status": "OK",
          "protocol": "0",
          "createAt": "2023-01-26T14:08:56.477Z",
          "score": 800
        }
      ]
    },
    {
      "service": "TYPIFICATION",
      "state": "OK",
      "result": [
        {
          "status": "OK",
          "protocol": "0",
          "createAt": "2023-06-06T20:58:42.104Z",
          "faceA": "https://api.dev.certiface.io/result/image/a500afcb-cd71-4dda-a81d-f0adf063b1a5/1686085075928",
          "faceB": "https://api.dev.certiface.io/result/image/a500afcb-cd71-4dda-a81d-f0adf063b1a5/1686085076300",
          "documentType": "CNH",
          "documentFound": true
        }
      ]
    },
    {
      "service": "OCR",
      "state": "OK",
      "result": [
        {
          "faceA": "https://api.dev.certiface.io/result/image/a500afcb-cd71-4dda-a81d-f0adf063b1a5/1686085075928",
          "faceB": "https://api.dev.certiface.io/result/image/a500afcb-cd71-4dda-a81d-f0adf063b1a5/1686085076300",
          "documentType": "CNH",
          "documentFound": true,
          "state": "SP",
          "document": "CNH",
          "name": "JOÃO DA SILVA",
          "parentage": "TIAO SILVA",
          "birthDate": "27/07/1980",
          "formattedBirthDate": "1985-01-27",
          "issueDate": "18/04/2018",
          "formattedIssueDate": "2018-04-18",
          "creationDate": "2023-06-06 20:58:13",
          "fatherName": "TIAO SILVA",
          "motherName": "WILLMA SILVA ",
          "status": "OK",
          "protocol": "0",
          "createAt": "2023-06-06T20:58:42.213Z",
          "originDoc": "41600800 SSP/SP\n",
          "registrationNumber": "98300123301",
          "expirationDate": "18/04/2023",
          "firstLicense": "20/02/2004",
          "location": "SOROCABA, SP\nPORTADOR",
          "securityCode": "40000005614",
          "mirror": "0000090332",
          "renach": "SP000000582"
        }
      ]
    }
  ]
}

📘

Conheça os atributos de todos os resultados!

Conheça as descrições dos retornos de cada serviço executado na jornada do usuário nesta documentação.