Desenvolvedor de sinal OneSpan: notificação de evento de retorno de chamada - parte 2

Duo Liang, 17 de Abril de 2019
OneSpan Sign Developer: Callback Event Notification – Part 2

Nisso primeira parte desta série de blogs, analisamos os possíveis usos de diferentes notificações de eventos e os fluxos de trabalho recomendados, configurando o ouvinte de retorno de chamada sempre que você precisar pesquisar transações, assinante ou qualquer outra informação. 

Neste blog, mostraremos o processo comum de tratamento de uma solicitação de retorno de chamada e todos os detalhes técnicos interessantes sobre as notificações de eventos de retorno de chamada. Sem mais delongas, vamos começar!

Registre-se para receber notificações de eventos

Antes que o OneSpan Sign possa notificá-lo sobre um evento, você deve primeiro registrar seu URL de retorno de chamada ou uma chave opcional de retorno de chamada, além de especificar quais eventos requerem notificação. Você pode acompanhar o nosso Configurar notificações de retorno de chamada guia sobre como se registrar para receber notificações de eventos programaticamente ou simplesmente fazê-lo através do portal da web na guia Integração na página Admin, conforme mostrado abaixo.4-17-1

Criar um ouvinte de retorno de chamada

Agora você está pronto para criar um ouvinte de webhook! O diagrama abaixo mostra todas as etapas necessárias para lidar com uma solicitação de postagem. A partir daí, explicaremos os detalhes técnicos de acordo. Este é um processo geral que pode ser aplicado a qualquer linguagem de programação ou estrutura da web com a qual você está desenvolvendo atualmente.4-17-2

Ponto de ouvinte de retorno de chamada 1

Primeiro, você precisa de um URL público para o OneSpan Sign ligar. Apenas para fins de teste, você pode obter um temporário Ngrok .
Portanto, quando ocorre um evento, como quando uma transação é concluída, o OneSpan Sign envia uma solicitação HTTP POST para o URL registrado nesta primeira seção. 

Ponto 2 e 3 do ouvinte de retorno de chamada

Lembra da chave de retorno de chamada que você definiu no registro? Esse token secreto é usado para identificar que a chamada POST era realmente do OneSpan Sign. Isso ajuda a confirmar que você não está recebendo chamadas falsas.
A chave de retorno de chamada que você registrou é passada pelo cabeçalho de autorização como "Básico {chave de retorno de chamada}".  
Depois de validar que a solicitação contém seu segredo compartilhado, você pode continuar processando a solicitação.

Ponto de ouvinte de retorno de chamada 4

As informações do evento são passadas no corpo da solicitação, que inclui um objeto JSON que contém o tipo e os dados associados a esse evento.
Abaixo estão alguns exemplos de carga útil de retorno de chamada:

O pacote foi criado
{" @class ":" com.silanis.esl.packages.event.ESLProcessEvent "," nome ":" PACKAGE_CREATE "," sessionUser ":" 18EZDL44xgsX "," packageId ":" wVdZEaPD2igwUnFGJBjDD0dpO7k = ", mensagem:" null ":" null: " : null, "createdDate": "2018-06-30T20: 04: 55.384Z"}

O pacote foi enviado
{" @class ":" com.silanis.esl.packages.event.ESLProcessEvent "," name ":" PACKAGE_ACTIVATE "," sessionUser ":" 18EZDL44xgsX "," packageId ":" 5n4obeO8jYoPp126Cm-Y3fxdfbo = "," mensagem ": nula," documentId ": null," createdDate ":" 2018-06-30T20: 09: 50.425Z "}

Documento de consentimento aceito do assinante 1
{" @class ":" com.silanis.esl.packages.event.ESLProcessEvent "," name ":" DOCUMENT_SIGNED "," sessionUser ":" 44aafb7c-97b9-40e1-bb59-eb76c7d2a484 "," packageId ":" 5n4obeO8jYoPp12 " , "message": null, "documentId": "consentimento padrão", "createdDate": "2018-06-30T20: 10: 51.002Z"}

O assinante 1 preencheu um documento
{" @class ":" com.silanis.esl.packages.event.ESLProcessEvent "," name ":" DOCUMENT_SIGNED "," sessionUser ":" 44aafb7c-97b9-40e1-bb59-eb76c7d2a484 "," packageId ":" 5n4obeO8jYoPp12 " , "message": null, "documentId": "7caf46cdd75f7a411bf8c22793b84fa79d8d180becc40691", "createdDate": "2018-06-30T20: 12: 12.256Z"}

Pacote de assinatura completo do assinante 1
{" @class ":" com.silanis.esl.packages.event.ESLProcessEvent "," name ":" SIGNER_COMPLETE "," sessionUser ":" 44aafb7c-97b9-40e1-bb59-eb76c7d2a484 "," packageId ":" 5n4obeO8jYoPdf " , "message": null, "documentId": null, "createdDate": "2018-06-30T20: 12: 12.272Z"}

O pacote foi concluído
{" @class ":" com.silanis.esl.packages.event.ESLProcessEvent "," name ":" PACKAGE_COMPLETE "," sessionUser ":" e00696ec-d6f5-4feb-89c5-a5ce002a6c66 "," packageId ":" 5n4obeO8jYdx " , "message": null, "documentId": null, "createdDate": "2018-06-30T20: 15: 01.038Z"}

Desativação do assinante 1:
{" @class ":" com.silanis.esl.packages.event.ESLProcessEvent "," nome ":" PACKAGE_OPT_OUT "," sessionUser ":" b5381b13-991e-4179-9f9b-d4e1ec9d06bb "," packageId ":" J5tyJalzG49 " mensagem ":" as informações pessoais não estão corretas "," documentId ": null," createdDate ":" 2018-06-30T20: 16: 29.763Z "}

Observe que o corpo de cada chamada pode variar com base no tipo de evento de notificação.

Ponto 5 e 6 do ouvinte de retorno de chamada

De acordo com o nome do evento, você pode distribuir a tarefa para stub funções para lidar com ela de acordo com sua lógica de negócios. Isso foi recomendado na primeira parte desta série de blogs. Se sua função de serviço tiver um fluxo de trabalho complexo e consumir a solicitação por um longo tempo, é melhor usar um método assíncrono para evitar causar erro de tempo limite. Para a implementação atual, a configuração de tempo limite de retorno de chamada foi de 20 segundos e pode variar entre diferentes instâncias.

Em seguida, retorne um código de status HTTP 200 de volta ao OneSpan Sign indicando que você recebeu com êxito o retorno de chamada. 

E se eu perder uma notificação?

A falta de uma notificação é um risco possível ao usar o mecanismo de notificação de eventos. 

Quando um retorno de chamada falha, um email é enviado. A partir da versão 11.21, esse email foi aprimorado para incluir o motivo da falha. Por exemplo, se houver uma exceção de tempo limite, um erro de "recurso não pode ser encontrado" ou outro código de erro, esses e-mails podem ajudar a solucionar a causa da falha. 4-17-3

Além disso, você pode pesquisar ativamente seus eventos a cada 6, 12 ou 24 horas como um backup para reduzir as perdas caso uma notificação seja perdida.

Acima, havia todo o conhecimento técnico necessário que você precisa conhecer para configurar um ouvinte de retorno de chamada. Nos próximos blogs, demonstraremos alguns projetos de amostra usando diferentes idiomas e estruturas, seguindo as etapas mencionadas aqui.

Se você tiver alguma dúvida sobre este blog ou qualquer outra coisa relacionada à integração do OneSpan Sign ao seu aplicativo, visite o Fóruns da comunidade de desenvolvedores . Seu feedback é importante para nós!

Comunidade de desenvolvedores OneSpan Sign

Comunidade de desenvolvedores OneSpan Sign

Participe da comunidade de desenvolvedores do OneSpan Sign! Fóruns, blogs, documentação, downloads de SDK e muito mais.

Junte-se hoje