Simply

Integração via Webhook

Integração via Web Hook

Introdução

O termo webhook é aplicado para um tipo de integração passiva, geralmente orientada a eventos que ocorrem no sistema, cujo objetivo é a passagem de informações entre sistemas sem depender de desenvolvimento de um serviço de integração explícito para tal propósito.

O sistema S-Works permite a configuração de Webhooks, por workflow, com objetivo de levar informações sobre o status de processamento do processo, dados sobre pendências documentais, dados de objetos de relacionamento, tarefas manuais executadas e respectivos usuários executores e até documentos anexados ao processo e seus metadados.

Configuração

Através da tela de configurações de workflow, em um workflow que esteja no status de "Rascunho", clique na aba "Web Hooks" e em seguida em "inserir web hook".

O formulário de configuração do web hook permite que sejam especificados:

Campo
Descrição
Nome
Um nome amigável para web hook de até 255 caracteres.
URL
Endereço completo para onde o web hook irá enviar o payload.
Enviar campos do documento?
Booleano que indica se os campos/metadados dos documentos devem ser retornados no payload.
Enviar documentos em base64?
Booleano que indica se os documentos devem ser retornados no payload. Se marcado, os documentos serão devolvidos no formato base64.
Tipo de Evento
Indica qual o tipo de evento cujo web hook foi disparado.
Formato de Saída
Indica se o payload deve ser enviado em formato JSON ou XML.
Filtro de Formulários
Filtra quais tipos de formulários tipificados devem ser retornados no payload. Caso não informado, informações de todos os formulários serão devolvidas.
Filtro de Parâmetros
Filtra quais os dados de entrada devem ser retornados no payload. Caso não informado, todos os dados de entrada serão incluídos no payload.
Autenticação
Tipo de autenticação que eventualmente deve ser utilizada para conseguir invocar o endpoint disponível na URL.

Caso seja configurado o envio de documentos pelo Webhook, um aumento considerável no tamanho da requisição será gerado. Use somente quando imprescindível para o processo de negócio.

Autenticação do Web Hook

A configuração de um mecanismo de autenticação é facultativo para o web hook, e quando ausente, o sistema fará a requisição no endpoint diretamente.
Porém, caso o endpoint esteja protegido, a configuração de um mecanismo de autenticação se faz necessária.
Atualmente o sistema possui as seguintes configurações de autenticação, análogas às configurações de autenticação para Web APIs, que podem ser configuradas através da tela de "Autenticação de APIs".
  1. Basic Authorization: autenticação básica informando usuário e senhas via headers.
  2. OAuth2 - Client Credentials: autenticação com padrão OAuth 2.0 do tipo de concessão "client credentials".
  3. OAuth2 - Password: autenticação com padrão OAuth 2.0 do tipo de concessão "password".
Uma outra forma comumente utilizada para assegurar o envio do web hook de forma confiável é a utilização de padrão de assinatura de requisição HMAC, porém este ainda não está disponível no sistema,

Execução do Webhook

O disparo de web hook é feito através de tarefa específica no workflow, configurada usando a API Core, com o método "DispararWebHook".
Basta configurar qual o tipo de evento desejado, e a tarefa irá realizar o disparo para todos os web hooks configurados no workflow que correspondam ao tipo de evento informado.



Requisição do Web Hook

Os disparos de web hook são sempre feitos através do verbo POST apontando para a URL configurada.
O sistema não analisa o conteúdo de resultado do web hook disparado, considerando sucesso para todas as requisições cujo status de resposta esteja entre 200-299.
Caso todas as respostas recebidas tenham obtido sucesso, a tarefa que disparou o web hook ficará com status aprovada.
Caso ocorra um status divergente dos status de sucesso nas respostas obtidas, a tarefa de disparo ficará com status de falha.

O sistema sempre envia requisição com verbo POST nos disparos de web hook. Tenha certeza que o endpoint configurado na URL esteja preparado para receber requisições utilizando este verbo.
Atualmente, qualquer falha de conectividade ou de resposta de insucesso fará com que a tarefa de disparo do Web Hook fique com status de falha. Caso ocorra uma falha, somente o reinício de tarefas fará com que uma nova tentativa de comunicação seja feita.

Exemplos de Payload


Lista de tipos de eventos do web hook:
  1. Pendência = 0
  2. Aprovado = 1
  3. Reprovado = 2
  4. Cancelado = 3
  5. Resultado da Tipificação = 4
A seguir alguns exemplo de payload do web hook.

Exemplo com retorno de dados de pendências documentais, atividades manuais executadas:
{
  "DonoProcesso"null,
  "UsuariosAtividadeManual": [
    {
      "Usuario""superuser",
      "DataUltimaAtuacao""2019-05-14T15:10:24.307"
    }
  ],
  "PendenciasDocumentos": [
    {
      "Formulario""Comprovante Residência",
      "Motivo""Maria",
      "Observacoes""Realizando teste de webhook.",
      "Usuario""superuser"
    }
  ],
  "Parametros": [
    {
      "Nome""Proposta",
      "Valor""123"
    },
    {
      "Nome""Nome",
      "Valor""MARIA JOSE DOS SANTOS"
    },
    {
      "Nome""DataNascimento",
      "Valor""12/12/1990"
    }
  ],
  "Documentos": [
    {
      "Nome""Cp1_0045209179.jpg",
      "NomeTipificacao""Identificacao Pessoal",
      "Status""Pendente",
      "NivelAnalise"0,
      "BytesBase64""",
      "Campos": {}
    },
    {
      "Nome""0045209175.jpg",
      "NomeTipificacao""Comprovante Residência",
      "Status""Reprovado",
      "NivelAnalise"0,
      "BytesBase64""",
      "Campos": {}
    }
  ],
  "Relacionamentos": [],
  "AtividadesExecutadas": [
    {
      "OrdemTarefa"11,
      "NomeTarefa""Validar Nome",
      "TipoAtividade"2,
      "Resposta"0,
      "Comentarios""Realizando teste de webhook.",
      "DataCriacao""2019-05-14T15:09:04.91",
      "DataAtribuicao""2019-05-14T15:09:35.07",
      "DataExecucao""2019-05-14T15:09:43.277",
      "UsuarioExecucao""superuser"
    },
    {
      "OrdemTarefa"12,
      "NomeTarefa""Validar Data de Nascimento",
      "TipoAtividade"2,
      "Resposta"0,
      "Comentarios""Realizando teste de webhook.",
      "DataCriacao""2019-05-14T15:09:05.473",
      "DataAtribuicao""2019-05-14T15:09:43.277",
      "DataExecucao""2019-05-14T15:09:51.483",
      "UsuarioExecucao""superuser"
    }
  ],
  "TipoEvento"1,
  "CodigoProcesso"8326,
  "Identificador""1c4b6429-3b83-4d04-8169-3e30fdb9d185",
  "Observacoes"null
}
Exemplo com retorno de dados de relacionamentos:
{
  "DonoProcesso"null,
  "UsuariosAtividadeManual": [],
  "PendenciasDocumentos": [],
  "Parametros": [
    {
      "Nome""Cpf",
      "Valor""123456789"
    },
    {
      "Nome""Matricula",
      "Valor""1642079070"
    },
    {
      "Nome""NomeCliente",
      "Valor""MARIO FERNANDES PEREIRA"
    },
    {
      "Nome""NumerodaProposta",
      "Valor""78033"
    }
  ],
  "Documentos": [],
  "Relacionamentos": [
    {
      "Objetos": [
        {
          "Parametros": [
            {
              "Nome""SubValidacaoInterna",
              "Valor""true"
            },
            {
              "Nome""SubValidacaoExterna",
              "Valor""false"
            }
          ]
        }
      ]
    }
  ],
  "AtividadesExecutadas": [ ],
  "TipoEvento"1,
  "CodigoProcesso"8498,
  "Identificador""59e887b9-3372-45a6-9ef3-0854a148f38c",
  "Observacoes"null
}


Abaixo exemplo de envio do tipo de evento 4 - ResultadoTipificacao

{
  "DonoProcesso": null,
  "UsuariosAtividadeManual": [],
  "PendenciasDocumentos": [],
  "Parametros": [
    {
      "Nome": "Nome",
      "Valor": "alber"
    },
    {
      "Nome": "CPF",
      "Valor": "07567513565"
    },
    {
      "Nome": "Nomereceita",
      "Valor": "sfsdf"
    }
  ],
  "Documentos": [
    {
      "Nome": "CNH.jpg",
      "NomeTipificacao": "Identificacao Pessoal",
      "Status": "Pendente",
      "NivelAnalise": 0,
      "BytesBase64": "",
      "Campos": {}
    },
    {
      "Nome": "Cp0_CNH.jpg",
      "NomeTipificacao": "CNH",
      "Status": "Pendente",
      "NivelAnalise": 0,
      "BytesBase64": "",
      "Campos": {}
    },
    {
      "Nome": "Cp1_CNH.jpg",
      "NomeTipificacao": "CNH Verso",
      "Status": "Pendente",
      "NivelAnalise": 0,
      "BytesBase64": "",
      "Campos": {}
    }
  ],
  "Relacionamentos": [],
  "AtividadesExecutadas": [],
  "TipoEvento": 4,
  "CodigoProcesso": 8803,
  "Identificador": "2857dcf7-fc0f-43b0-9519-78b5471bf11d",
  "Observacoes": null
}

Perguntas Frequentes

Além de um usuário e senha quais configurações vocês usam pra garantir que é o cliente se comunicando com vocês?

Considerando um ambiente em nuvem, pode (e devemos) restringir os acessos ao servidor usando apenas o IPs de saída do gateway do cliente, evitando com que requisições de fontes desconhecidas sequer atinjam a aplicação.

Como o cliente vai garantir que é a Simply submetendo mensagens pro nosso Web Hook?

Atualmente o webhook não realiza nenhuma assinatura de conteúdo para garantir que a requisição é proveniente do S-Works para o endpoint webhook do cliente. Há uma PBI para isso (36083) para assinarmos o conteúdo usando uma chave compartilhada, que pode ser mais simples de implementar e não impacta os clientes legados (usar autorização com HMAC).

Contudo, da mesma forma que no item acima, o cliente pode restringir os acessos aos seus endpoints que receberão a requisição de web hook. Ainda temos a possibilidade de configurar uma VPN de ponta-a-ponta, colocando uma camada adicional de segurança na requisição.
    • Related Articles

    • Manual API de Integração RESTful Atomics Plus

      Manual API integração RESTful Atomics Plus Introdução A API RESTful do Atomics Plus permite que sistemas de terceiros criem, manipulem e submetam processos à workflows no sistema. O objetivo dessa documentação é mostrar as principais operações ...
    • S-WORKS Manual API integração Rest

      Manual API integração RESTful S-Works Introdução A API RESTful do S-Works permite que sistemas de terceiros criem, manipulem e submetam processos à workflows no sistema. O objetivo dessa documentação é mostrar as principais operações necessárias para ...
    • S-Works - Camada Integração

      1. Escopo dos serviços  Neste manual estão contidas todas as informações necessárias referentes às integrações do S-Works. 2. Webhook  O Webhook permite a visualização gerencial dos resultados e informações geradas através de dashboards, indicadores ...
    • S-Works - Manual de Instalação da Versão 2.0 - v2 2 1

      Versionamento Versão Data Comentários 1.0 23/09/2020 Versão inicial do documento. Atualização do manual para conter etapas de instalação 2.0 20/01/2021 manual do sistema e seus módulos, assim como configuração dos mesmos. 2.1 21/01/2021 Revisão, ...
    • Integração Docusign

      Criamos o método EnviarDocumentoParaAssinatura na API da Docusign. Ele possibilita enviar documentos do processo para serem assinados digitalmente através da Integração com a DocSign. Configuração do Método EnviarDocumentoParaAssinatura 1) Clique em ...