Configurar webhooks

Visão geral

Um webhook é um retorno de chamada HTTPS definido pelo usuário que é acionado quando um evento específico ocorre no site de origem (neste caso, o Adobe Acrobat Sign).

Efetivamente, um webhook é apenas um serviço web que aceita solicitações HTTPS POST de uma origem. Portanto, um webhook é um serviço REST que aceita dados ou um fluxo de dados.

Webhooks são para comunicação de serviço a serviço em um Modelo de push.

Quando ocorre um evento de acionamento, o Acrobat Sign constrói um POST HTTPS com um corpo JSON e o envia ao URL especificado.

 

Os webhooks oferecem vários benefícios em relação ao método Callback anterior. Entre eles:

  • Os administradores podem ativar seus próprios webhooks sem precisar envolver o suporte do Acrobat Sign para listar o URL de retorno de chamada
  • Webhooks são melhores em termos de "atualidade" de dados, eficiência de comunicação e segurança. Não há necessidade de sondagem
  • Os webhooks permitem diferentes níveis de escopo (Conta/Grupo/Usuário/Recurso) com facilidade. 
  • Os webhooks são uma solução de API mais moderna, permitindo uma configuração mais fácil para aplicativos modernos
  • Vários webhooks podem ser configurados por escopo (Conta/Grupo/Usuário/Recurso), enquanto os Callbacks precisavam ser exclusivos
  • Os webhooks permitem a seleção dos dados a serem retornados, enquanto os Callbacks são uma solução "tudo ou nada"
  • Os metadados transportados com um webhook podem ser configurados (básicos ou detalhados)
  • Os webhooks são muito mais fáceis de criar, editar ou desativar conforme necessário, já que a interface está totalmente sob o controle do administrador.
Observação:

Este documento concentra-se principalmente na interface de webhooks no aplicativo web do Acrobat Sign (anteriormente Adobe Sign).

Os desenvolvedores que estão procurando detalhes da API podem encontrar mais informações aqui:


Como é usada

Os administradores precisarão primeiro de um serviço de webhook pronto para aceitar o push de entrada do Acrobat Sign. Há muitas opções a esse respeito e, desde que o serviço possa aceitar solicitações POST e GET, o webhook terá êxito.

Quando o serviço estiver em funcionamento, um administrador do Acrobat Sign poderá criar um novo webhook na interface do Webhook no menu Conta, do site do Acrobat Sign.

Os administradores podem configurar o webhook para ser acionado para eventos de Contrato, Formulário web ou Envio em massa.

O escopo do webhook pode incluir a conta inteira ou grupos individuais por meio da interface do administrador. Os escopos Usuário e Recurso também são possíveis por meio da API

O tipo de dados que é enviado para o URL é configurável e pode incluir itens como Informações do contrato, Informações do participante, Documento assinado e assim por diante.

Depois que o webhook é configurado e salvo, o Acrobat Sign envia um novo objeto JSON para o URL definido sempre que o evento de acionamento é capturado. Nenhuma manipulação contínua do webhook é necessária, a menos que você queira alterar os critérios do acionador do evento ou a carga JSON.


Verificação de intenção do URL do webhook

Antes de registrar um webhook com êxito, o Acrobat Sign verifica se o URL do webhook fornecido na solicitação de registro realmente deseja receber notificações ou não. Para essa finalidade, quando uma nova solicitação de registro do webhook é recebida pelo Acrobat Sign, ele primeiro faz uma solicitação de verificação ao URL do webhook. Esta solicitação de verificação é uma solicitação GET HTTPS enviada ao URL do webhook. Ela tem um cabeçalho HTTP personalizado X-AdobeSign-ClientId. O valor nesse cabeçalho é definido como a ID do cliente (ID do aplicativo) do aplicativo da API que está solicitando a criação/registro do webhook. Para registrar um webhook com êxito, o URL do webhook responde a essa solicitação de verificação com um código de resposta 2XX E, além disso, ele DEVE enviar o valor da mesma ID de cliente de uma das duas maneiras a seguir:

  • Em um cabeçalho de resposta X-AdobeSign-ClientId. É o mesmo cabeçalho transmitido na solicitação e que deve ser repetido na resposta.
  • No corpo da resposta JSON, com a chave de xAdobeSignClientId e seu valor sendo a mesma ID de cliente enviada na solicitação.

O webhook será registrado com êxito apenas em uma resposta de sucesso (código de resposta 2XX) e validação da ID do cliente no cabeçalho ou no corpo da resposta. A finalidade dessa solicitação de verificação é demonstrar que o URL do webhook realmente deseja receber notificações nesse URL. Se você inseriu acidentalmente o URL errado, o URL não responderia corretamente à solicitação de verificação de intenção e o Acrobat Sign não enviará nenhuma notificação para esse URL. Além disso, o URL do webhook também pode validar que ele receberia notificações apenas por meio dos webhooks registrados por um aplicativo específico. Isso pode ser feito validando a ID do cliente do aplicativo passado no cabeçalho X-AdobeSign-ClientId. Se o URL do webhook não reconhecer essa ID de cliente, ele NÃO DEVERÁ responder com o código de resposta de sucesso, e o Acrobat Sign garantirá que o URL não seja registrado como um webhook.

A verificação da chamada de URL do webhook será feita nos seguintes cenários:

  • Registro do Webhook: se essa verificação da chamada de URL do webhook falhar, o webhook não será criado
  • Atualização do Webhook: INATIVO para ATIVO: se essa verificação da chamada de URL do webhook falhar, o estado do webhook não será alterado para ATIVO

Como responder a uma notificação de webhook

O Acrobat Sign executa uma verificação implícita de intenção em cada solicitação de notificação do webhook enviada ao URL do webhook. Assim, cada solicitação HTTPS de notificação do webhook também contém o cabeçalho HTTP personalizado chamado X-AdobeSign-ClientId. O valor desse cabeçalho é a ID do cliente (ID do aplicativo) do aplicativo que criou o webhook. Consideraremos a notificação do webhook entregue com sucesso apenas se uma resposta de sucesso (código de resposta 2XX) for retornada e a ID do cliente for enviada no cabeçalho HTTP (X-AdobeSign-ClientId) ou em um corpo de resposta JSON com xAdobeSignClientId como chave e o valor como a mesma ID de cliente. Caso contrário, tentaremos enviar a notificação novamente para o URL do webhook até que as tentativas sejam esgotadas.

Como mencionado acima, o cabeçalho “X-AdobeSign-ClientId”, que é incluído em cada solicitação de notificação do Sign, deve ter seu valor (ID do cliente) repetido como resposta em uma de duas maneiras:

1. Cabeçalho HTTP X-AdobeSign-ClientId e o valor como essa ID de cliente

Exemplo de código JavaScript para obter a ID do cliente, validá-la e, em seguida, retorná-la no cabeçalho da resposta

// Buscar ID do cliente

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

 

//Validar

if (clientid ==="BGBQIIE7H253K6") //Substituir “BGBQIIE7H253K6” pela ID de cliente do aplicativo no qual o webhook foi criado

{

    //Retornar no cabeçalho da resposta

    response.headers['X-AdobeSign-ClientId'] = clientid;

    response.status = 200; // valor padrão

}

Exemplo de código PHP para obter a ID do cliente, validá-la e depois retorná-la no cabeçalho da resposta

 

<?php

// Buscar ID do cliente

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Validar

if($clientid == "BGBQIIE7H253K6") //Substituir “BGBQIIE7H253K6” pela ID de cliente do aplicativo no qual o webhook foi criado

{

    //Retornar no cabeçalho da resposta

   header("X-AdobeSign-ClientId:$clientid");

   header("HTTP/1.1 200 OK"); // valor padrão

}

?>

 


2. Corpo da resposta JSON com xAdobeSignClientId como chave e o valor como a mesma ID de cliente

Exemplo de código JavaScript para obter a ID do cliente, validá-la e retorná-la no corpo da resposta

// Buscar ID do cliente

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

 

 

//Validar

if (clientid ==="BGBQIIE7H253K6") //Substituir “BGBQIIE7H253K6” pela ID de cliente do aplicativo no qual o webhook foi criado

{

    var responseBody = {

                         "xAdobeSignClientId" : clientid // Retorna a ID de cliente no corpo

                       };

    response.headers['Content-Type'] = 'application/json';

    response.body = responseBody;

    response.status = 200;

}

Exemplo de código PHP para obter a ID do cliente, validá-la e retorná-la no corpo da resposta

<?php

// Buscar ID do cliente

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Validar

if($clientid == "BGBQIIE7H253K6") //Substituir “BGBQIIE7H253K6” pela ID de cliente do aplicativo no qual o webhook foi criado

{

   //Retornar no corpo da resposta

   header("Content-Type: application/json");

   $body = array('xAdobeSignClientId' => $clientid);

   echo json_encode($body);

   header("HTTP/1.1 200 OK"); // valor padrão

}

?>

Amostra do corpo do JSON da resposta

{

    "xAdobeSignClientId": "BGBQIIE7H253K6"

}

Pré-requisitos

Você precisará de:

  1. Uma conta da Microsoft com licença para criar Aplicativos de funções do Azure
  2. Um Aplicativo de função do Azure existente. Você pode criar um usando https://docs.microsoft.com/pt-br/azure/azure-functions/functions-create-first-azure-function 
  3. Conhecimento básico de Javascript para que você possa entender e escrever o código na linguagem que quiser


Etapas para criar um Acionador de funções do Azure que serve como um webhook do Acrobat Sign

Para criar uma função de acionamento HTTP Javascript:

1. Faça logon usando sua conta da Microsoft https://portal.azure.com/

2. Abra o Aplicativo de Função do Azure exibido na guia Aplicativos de Função.

Isso abrirá sua lista de Aplicativos de Função do Azure:

3. Escolha o aplicativo no qual deseja criar essa nova função

4. Clique no botão Criar (+) para criar uma nova função do Azure

 

5. Selecione Webhook + API como o cenário e Javascript como a linguagem

6. Clique em Criar esta função

Uma nova função que tem a capacidade de manipular uma solicitação de API de entrada é criada.


Adicione a lógica para registrar o webhook do Acrobat Sign

Antes de registrar um webhook com êxito, o Acrobat Sign verifica se o URL do webhook fornecido na solicitação de registro realmente deseja receber notificações ou não. Para essa finalidade, quando uma nova solicitação de registro do webhook é recebida pelo Acrobat Sign, ele primeiro faz uma solicitação de verificação ao URL do webhook. Esta solicitação de verificação é uma solicitação HTTPS GET enviada ao URL do webhook com um cabeçalho HTTP personalizado X-AdobeSign-ClientId. O valor neste cabeçalho é definido para a ID de cliente do aplicativo que está solicitando a criação/registro do webhook. Para registrar um webhook com êxito, o URL do webhook deve responder a essa solicitação de verificação com um código de resposta 2XX E, além disso, deve retornar o valor da mesma ID de cliente de uma das duas maneiras a seguir.

Há duas opções que você pode seguir:


Opção 1: passar a ID do cliente no X-AdobeSign-ClientId como cabeçalho da resposta

Passar o X-AdobeSign-ClientId no cabeçalho da resposta. Esse é o mesmo cabeçalho transmitido na solicitação e que deve ser repetido na resposta.

Substitua o arquivo Index.js pelo seguinte:

module.exports = function (context, req) {

    var clientId = req.headers['x-adobesign-clientid'];

    // Validar que a ID de cliente de entrada é autêntica

    if (clientId === '123XXX456') {

        context.res = {

            // status: 200, /* O padrão é 200 */ // qualquer resposta 2XX é aceitável

            body: "Notification Accepted",

            headers : {

                'x-adobesign-clientid' : req.headers['x-adobesign-clientid']

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Illegitimate Call identified"

        };

    }

    context.done();

};

 

Teste o comportamento simulando a solicitação:

1. Clique no botão Teste no canto mais à direita

2. Simule a solicitação

Embora os cabeçalhos de resposta não sejam mostrados acima, você pode observá-los ao simular no Postman/DHC ou qualquer outro serviço.


Opção 2: passe a ID do cliente no corpo da resposta com a chave xAdobeSignClientId

No corpo da resposta JSON, com a chave xAdobeSignClientId e seu valor sendo a mesma ID de cliente enviada no cabeçalho de solicitação.

Substitua o arquivo Index.js pelo seguinte:

module.exports = function (context, req) {

    var clientId = req.headers['x-adobesign-clientid'];

    // Validar que a ID de cliente de entrada é autêntica

    if (clientId === '123XXX456') {

        context.res = {

            // status: 200, /* O padrão é 200 */ // qualquer resposta 2XX é aceitável

            body: {

                'xAdobeSignClientId' : clientId

            },

            headers : {

                'Content-Type' : 'application/json'

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Illegitimate Call identified"

        };

    }

    context.done();

};

 

Teste o comportamento simulando a solicitação

1. Clique no botão Teste no canto mais à direita

2. Simule a solicitação

Observe também que o mesmo comportamento para a ID de cliente é esperado quando o URL do webhook recebe notificações POST. 


Pronto para uso

Depois de verificar o comportamento, o URL do webhook é funcional de acordo com os padrões do Acrobat Sign. Você pode atualizar ainda mais a lógica personalizada conforme suas necessidades.

 

Obter o URL da função

  • Clique em Obter o URL da função

 

Copie o URL e use-o para criar webhooks no Acrobat Sign.

Criação da função AWS Lambda

Para criar uma função AWS Lambda, faça logon no AWS Management Console e selecione o serviço AWS Lambda na lista de serviços.

  • Clique em Criar uma função Lambda usando a opção "Author From Scratch" 
  • Na página Configurar função, insira o nome da função "lambdaWebhooks" e selecione o Node.js 4.3 como Runtime
  • Para a Função, escolha uma função existente ou crie uma nova a partir do(s) modelo(s)
    • Se você escolheu Criar nova função a partir do(s) modelo(s) insira um nome de função (por exemplo, role-lambda) e selecione Permissões simples de microsserviços na lista de Modelos de política 
  • Clique no botão Criar função

  • Na página da nova função de lambda do AWS, selecione "Editar código incorporado" como "Tipo de entrada de código" e mantenha o index.handler como Handler.
  • Adicionar lógica para registrar o webhook do Acrobat Sign

    Antes de registrar um webhook com êxito, o Acrobat Sign verifica se o URL do webhook fornecido na solicitação de registro realmente deseja receber notificações ou não. Para essa finalidade, quando uma nova solicitação de registro do webhook é recebida pelo Acrobat Sign, ele primeiro faz uma solicitação de verificação ao URL do webhook. Esta solicitação de verificação é uma solicitação HTTPS GET enviada ao URL do webhook com um cabeçalho HTTP personalizado X-AdobeSign-ClientId. O valor neste cabeçalho é definido para a ID de cliente do aplicativo que está solicitando a criação/registro do webhook. Para registrar um webhook com êxito, o URL do webhook deve responder a essa solicitação de verificação com um código de resposta 2XX E, além disso, deve retornar o valor da mesma ID de cliente de uma das duas maneiras a seguir. Observe também que o mesmo comportamento para a ID do cliente é esperado quando o URL do webhook recebe notificações POST. 

    Siga um destes dois casos:

    Caso 1: passar a ID do cliente no X-AdobeSign-ClientId como cabeçalho da resposta

    •  Passar X-AdobeSign-ClientId no cabeçalho da resposta. Esse é o mesmo cabeçalho transmitido na solicitação e que deve ser repetido na resposta.

      Snippet de código
      No arquivo index.js, substitua o trecho de código gerado automaticamente pelo seguinte código:

Exemplo de código do Node JS para obter a ID do cliente, validá-la e, em seguida, devolvê-la no cabeçalho da resposta

exports.handler = function index(event, context, callback) {

  // Buscar ID do cliente

  var clientid = event.headers['X-AdobeSign-ClientId'];

 

  //Validar

  if (clientid =="BGBQIIE7H253K6") //Substitua 'BGBQIIE7H253K6' pela ID do cliente do aplicativo no qual o webhook foi criado

  {

    var response = {

        statusCode: 200,

        headers: {

            "X-AdobeSign-ClientId": clientid

        }

     };

   callback(null,response);

  }

  else {

   callback("Oops!! illegitimate call");

  }

}

 

Caso 2: passar a ID do Cliente no corpo da resposta com a chave xAdobeSignClientId

No corpo da resposta JSON, com a chave de xAdobeSignClientId e seu valor sendo a mesma ID de cliente enviada na solicitação.

 

Trecho de código

Substitua o arquivo Index.js pelo seguinte:

Exemplo de código do Node JS para obter a ID do cliente, validá-la e, em seguida, devolvê-la no cabeçalho da resposta

exports.handler = function index(event, context, callback) {

 // Buscar ID do cliente

 var clientid = event.headers['X-AdobeSign-ClientId'];

  

 //Validar

 if (clientid =="BGBQIIE7H253K6") //Substitua 'BGBQIIE7H253K6' pela ID do cliente do aplicativo em que o webhook foi criado

 {

   var responseBody = {

        xAdobeSignClientId : clientid

   };

     

    var response = {

        statusCode: 200,

        body: JSON.stringify(responseBody)

    };

 

   callback(null,response);

 }

 else {

   callback("Opps!! illegitimate call");

  }

}

  • Salve a função. A função Lambda é criada e estamos quase prontos para usá-la em um webhook em tempo real.

 

Configuração do AWS API Gateway

Para tornar esse Lambda acessível publicamente por meio de um método HTTP, precisamos configurar o AWS API Gateway usando nossa função (criada acima) como back-end para a API.

No Console de Gerenciamento da AWS, selecione API Gateway nos serviços da AWS e clique no botão Criar API

  • No página Criar nova API, selecione Nova API e insira webhooks como o Nome da API.
  • Clique no botão Criar API
  • Selecione a lista suspensa Ações e selecione a opção Criar recurso
  • Verifique a opção Configurar como recurso proxy e digite validar como o Nome do recurso e {proxy+} no Caminho do Recurso
  • Deixe a opção Habilitar CORS do API Gateway desmarcada e clique no botão Criar recurso
  • Mantenha o Proxy de Função Lambda selecionado como Tipo de integração e selecione a região em que você criou a função Lambda na lista suspensa Região de Lambda (provavelmente é a mesma região onde você está criando o gateway da API).
  • Insira validar como a Função Lambda e clique no botão Salvar
  • Na janela pop-up Adicionar Permissão à Função Lambda, selecione OK

Se todas as etapas acima forem executadas com êxito, você verá algo como:

Implantação de API

A próxima etapa é implantar essa API para que ela fique pronta para uso.

  • No menu suspenso Ações, selecione Implantar API
  • Selecione [Novo Estágio] no Estágio de implantação e insira prod (ou o que quiser para identificar esse estágio) no Nome do estágio
  • Clique no botão Implantar

A API está pronta para uso e você pode encontrar o URL invocado na caixa azul, conforme mostrado abaixo:

Anote este URL, pois você precisará inseri-lo como seu URL de webhook em tempo real.

 

Pronto para uso

Está feito. Use o URL acima com "/{nodeJSfunctionName}" anexado como URL do webhook na solicitação da API POST /webhooks.  Depois de verificar o comportamento, o URL do webhook estará funcional de acordo com os
Padrões do Acrobat Sign. Você pode atualizar/adicionar a lógica personalizada conforme sua necessidade.


Opções de configuração

A configuração do webhook requer a definição de cinco elementos:

  • Nome: sugerimos um nome intuitivo que outros administradores possam entender prontamente
  • Escopo: o tamanho da captura do webhook. Conta e Grupo estão disponíveis na interface
    • A API é compatível com os escopos de Recurso, Conta, Grupo e Usuário
    • Somente um Escopo por webhook pode ser definido
  • URL: o URL de destino para o qual o Acrobat Sign enviou a carga JSON
  • Eventos: o acionador que faz com que o Acrobat Sign crie o JSON e o envie para o URL
    • Cada evento cria uma carga diferente relevante para o evento de acionamento
    • Vários Eventos podem ser incluídos em um webhook
  • Parâmetros de notificação: os Parâmetros de notificação identificam as seções do Evento carga JSON, permitindo que você selecione apenas as seções do Evento que são importantes para este webhook (reduzindo assim os dados desnecessários em seu URL).

 

Quando o webhook estiver totalmente definido, clique em Salvar e o novo webhook começará a reagir para acionar eventos imediatamente. 

Observação:

Configure o URL do webhook para responder às solicitações de verificação e notificação do webhook conforme o protocolo de verificação explicado acima. A ID do cliente (ID do Aplicativo) que será enviada para webhooks criados no aplicativo web do Acrobat Sign será - UB7E5BXCXY

Configurar o webhook


Escopos

  • Conta: todos os eventos inscritos que ocorrem na conta acionam o push 
    • Os administradores de conta têm autoridade para ver todos os webhooks definidos para a conta/todos os grupos.
  • Grupo: todos os eventos inscritos que ocorrem nesse grupo acionam o push. Os webhooks com escopo de grupo existem em apenas um grupo.
    • Os administradores de grupo verão apenas os webhooks dedicados ao grupo. Eles não podem ver os webhooks no nível da conta ou webhooks vinculados a outros grupos.
    • As contas com Usuários em vários grupos ativado verão a opção para definir o grupo ao qual o escopo deve ser aplicado.
  • Conta de usuário: todos os eventos inscritos para uma conta de usuário acionam o push. Os webhooks no nível do usuário só podem ser criados por meio da API.
  • Webhook de nível de recurso: isso será criado para um recurso específico. Os eventos específicos deste recurso serão enviados para a URL do webhook. Os webhooks baseados em recursos só podem ser criados por meio de API.


URL

Um URL de webhook é um servidor que escuta mensagens de notificação de POST HTTPS de entrada que são acionadas quando ocorrem eventos.

Você precisa desse URL para inscrever seu webhook para eventos.

  • O cliente deve incluir um URL HTTPS ao qual o Acrobat Sign possa fazer solicitações POST. Este URL deve estar disponível na Internet pública.  
    • Por exemplo, os URIs 127.0.0.1 e localhost não funcionarão.
    • O endpoint do URL deve estar escutando na porta 443.
  • Verifique se o webhook oferece suporte a solicitações POST para notificações de evento de entrada e solicitações GET para a solicitação de verificação.
  • O URL não deve ser bloqueado por um firewall.


Eventos

Abaixo, estão os eventos que podem acionar um push para o URL do webhook, agrupados pelo objeto.

Cada evento tem um modelo da carga JSON que pode ser entregue. (Clique no nome do evento para ver os detalhes da carga útil):

  • Envio em massa (antigo Mega Sign) — os eventos de Envio em massa dizem respeito apenas à criação do objeto pai do Envio em massa. Os contratos filho resultantes são rastreados como eventos de contrato.  
    • Todos os eventos de Envio em massa — todos os eventos de Envio em massa são incluídos. Se eventos adicionais forem definidos no futuro, eles serão incluídos automaticamente com essa configuração.  A carga JSON é baseada no evento individual que é acionado
    • Envio em massa criado — quando um Envio em massa é criado
    • Envio em massa compartilhado — quando um Envio em massa é compartilhado
    • Envio em massa recuperado — quando um Envio em massa é recuperado
  • Formulário web (antigo Widgets) — os eventos de formulário web dizem respeito apenas à criação do modelo de formulário web. Os contratos filho resultantes são rastreados como eventos de contrato.
    • Todos os eventos de Widget — todos os eventos de formulário web são incluídos. Se eventos adicionais forem definidos no futuro, eles serão incluídos automaticamente com essa configuração.  A carga JSON é baseada no evento individual que é acionado
    • Widget criado — quando um formulário web é criado
    • Widget ativado — quando um formulário web é ativado
    • Widget desativado — quando um formulário web é desativado
    • Widget modificado — quando um formulário web é modificado
    • Widget compartilhado — quando um formulário web é compartilhado
    • Falha na criação do widget — quando um formulário web é cancelado automaticamente devido a um problema de conversão


Parâmetros de notificação

Os Parâmetros de Notificação permitem personalizar a carga JSON apenas para elementos específicos do evento.

Por exemplo, em um evento de Participante do contrato substituído, você pode querer apenas as Informações do contrato e as Informações do participante, deixando de fora as Informações do documento e reduzindo o volume total no URL do webhook

 

  • Contrato
    • Informações do contrato — informações detalhadas do contrato com base no estado do contrato no momento do evento de acionamento
    • Informações do documento do contrato — inclui qualquer informação de documento gerada como resultado do evento
    • Informações do Participante do Contrato — inclui qualquer informação do participante como resultado do evento
    • Documento assinado do contrato — fornece o PDF assinado. 
      • Aplicável ao Fluxo de trabalho do contrato concluído e eventos Todos os contratos
  • Envio em massa
    • Informações de Envio em massa — informações detalhadas sobre o objeto de Envio em massa que acionou o evento
  • Formulário web
    • Informações do widget — informações detalhadas sobre o formulário web que acionou o evento
    • Informações do documento do widget — as informações do documento associadas ao modelo de formulário web
    • Informações do participante do widget — informações sobre os participantes definidos no modelo de formulário web


Autenticação SSL bidirecional

O SSL bidirecional, geralmente chamado de SSL do lado do cliente ou TLS mútuo, é um modo de SSL no qual o servidor e o cliente (navegador da Web) apresentam certificados para se identificarem.

Os administradores de conta podem configurar um certificado do lado do cliente na página Configurações de segurança.

O Acrobat Sign verifica os certificados SSL ao fornecer cargas para o URL do webhook. Os webhooks que não passam a verificação de certificado SSL não entregarão com a carga JSON com êxito. 

Use o SSL bidirecional para autenticar o cliente (Acrobat Sign) e o serviço de escuta para garantir que apenas o Acrobat Sign possa acessar o URL do webhook. 

Se o webhook foi criado por um Aplicativo de parceiro, ele usará um certificado de cliente (caso disponível) da Conta de aplicativo do parceiro para se identificar ao fazer chamadas de retorno do webhook.

Veja a seguir as perguntas mais comuns sobre o processo de verificação do servidor Web e a verificação da certificação do cliente.

Verificação do servidor Web

Durante o registro de um webhook, o Acrobat Sign verifica o URL do servidor do webhook.

Os clientes não poderão registrar o webhook se a conexão com o URL de retorno de chamada do webhook não puder ser concluída no Acrobat Sign.

Não.

O URL de retorno de chamada do webhook só pode ser HTTPS na porta 443.

O Acrobat Sign bloqueia o tráfego HTTPS de saída para todas as outras portas.

Uma boa maneira de verificar o certificado do servidor é usar a Ferramenta de diagnóstico de instalação DigiCert® SSL.

Insira apenas o nome do host, por exemplo: www.digicert.com

Problemas comuns incluem:

  • Problema: usar uma autoridade de certificação não confiável ou um certificado autoassinado

Correção: use um certificado SSL emitido por uma CA pública para o servidor de retorno de chamada do webhook.

CA não confiável

  • Problema: o servidor não está enviando o certificado intermediário

Correção: instale os certificados intermediários no servidor de retorno de chamada do webhook.

Consulte https://www.digicert.com/kb/ssl-certificate-installation.htm para obter informações detalhadas.

Certificados intermediários ausentes

Verificação de certificado de cliente

Para configurar um SSL bidirecional para um webhook, exigimos que o administrador faça upload de um arquivo .p12 (ou .pfx) que contenha a chave privada. O arquivo é armazenado com segurança na conta do cliente e o administrador tem controle total para removê-lo a qualquer momento.

Em uma configuração de webhook bidirecional, o Acrobat Sign é o chamador/cliente e precisa da chave privada para provar que a chamada é feita pelo Acrobat Sign em nome da conta do cliente.

  1. Verifique se o SSL bidirecional está habilitado

    O SSL bidirecional deve estar habilitado no servidor de retorno de chamada do webhook.

    Usando qualquer navegador da Web, conecte-se ao URL de retorno de chamada do webhook. Você deve obter:

    400 Solicitação inválida
    Nenhum certificado SSL foi enviado

    Isso significa que o servidor espera que o cliente envie certificados de cliente (ou seja, SSL bidirecional habilitado para o servidor).

    Se você não vir a mensagem acima, o SSL bidirecional não está ativado.

    Observação:

    Você pode usar o Postman e fazer uma solicitação POST para o URL de retorno de chamada do webhook. Você deve obter um resultado semelhante.

  2. Verificar certificado de cliente localmente

    A credencial do cliente pode ser um certificado autoassinado ou um certificado emitido por uma autoridade de certificação. No entanto, ele deve estar em conformidade com as seguintes extensões X.509 v3:

    Extensão X.509 v3

    Valor

    ExtendedKeyUsage

    clientAuth (OID: 1.3.6.1.5.5.7.3.2)

    KeyUsage

    digitalSignature

    O certificado do cliente deve ser um arquivo PKCS12 com a extensão .p12 ou .pfx e deve incluir ambos os certificados do cliente (para que o servidor possa verificar a identidade do cliente) e a chave privada do cliente (para que o cliente possa assinar digitalmente mensagens para que o servidor verifique durante o handshake SSL). 

    Use o comando openssl para verificar o arquivo p12 (pfx):

    openssl pkcs12 -info -in outfile.p12

    A senha da chave privada deve ser solicitada. A saída deve conter ambos os certificados, bem como uma chave privada criptografada, como:

    Bag Attributes
        localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
    subject=/C=US/ST=California/L=San Jose/O=Adobe Inc./CN=sp.adobesignpreview.com
    issuer=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
    -----BEGIN CERTIFICATE-----
    MIIGwDCCBaigAwIBAgIQAhJSKDdyQZjlbYO5MJAYOTANBgkqhkiG9w0BAQsFADBP
    MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE
    ...
    JAKQLQ==
    -----END CERTIFICATE-----
    Bag Attributes: <No Attributes>
    subject=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
    issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CA
    -----BEGIN CERTIFICATE-----
    MIIEvjCCA6agAwIBAgIQBtjZBNVYQ0b2ii+nVCJ+xDANBgkqhkiG9w0BAQsFADBh
    MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
    ...
    -----END CERTIFICATE-----
    Bag Attributes
        localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
    Key Attributes: <No Attributes>
    -----BEGIN ENCRYPTED PRIVATE KEY-----
    MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI7eNh2qlsLPkCAggA
    ...
    FHE=
    -----END ENCRYPTED PRIVATE KEY-----

    Os certificados devem incluir, no mínimo, o certificado da entidade final e os certificados intermédios. O ideal é incluir também o certificado da CA raiz.  

    Verifique se o arquivo .p12 ou .pfx está protegido por senha.

  3. Criar um certificado de cliente autoassinado (opcional)

    Os certificados do cliente podem ser emitidos por uma autoridade de certificação ou autoassinados, dependendo da sua necessidade.

    Para gerar um certificado de cliente autoassinado, use o seguinte comando openssl:

    openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

    Cuidado:

    Mantenha os arquivos resultantes em segredo, pois eles são seus certificados da CA autoassinados.

    Em seguida, gere o arquivo .p12 do cliente:

    1. Gerar uma chave privada para o cliente SSL:

      openssl genrsa -out client.key 2048

    2. Use a chave privada do cliente para gerar uma solicitação de certificado:

      openssl req -new -key client.key -out client.req

    3. Emita o certificado do cliente usando a solicitação de certificado e a chave/certificado da CA:

      openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer

    4. Converta o certificado do cliente e a chave privada para o formato pkcs#12 para uso pelos navegadores:

      openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12

    5. Remova a chave privada do cliente, o certificado do cliente e os arquivos de solicitação do cliente, pois o pkcs12 tem tudo o que você precisa.

      rm client.key client.cer client.req

  4. Verificar o certificado do cliente em relação ao servidor remoto

    • Use Postman para carregar o arquivo PFX do cliente em Configurações > Certificados.
    • Selecione Adicionar certificado para adicionar o certificado do cliente.
    Configurações do Postman

    • Configure o cabeçalho HTTP para x-adobesign-clientid:
    Configurar o cabeçalho

    Depois de configurado, envie uma solicitação POST para o URL de retorno de chamada do webhook.

    Você deve obter uma resposta 200.

  5. Por que o Acrobat Sign rejeita meu arquivo PFX mesmo depois de verificá-lo com o Postman?

    Se você seguiu o processo acima para a verificação do arquivo pfx e o Acrobat Sign ainda rejeita o arquivo pfx, é provável que o arquivo tenha sido gerado por uma ferramenta da Microsoft que pode produzir um arquivo PKCS12 não padrão.

    Nesse caso, use os comandos openssl abaixo para extrair os certificados e a chave privada do arquivo pfx e, em seguida, gere um arquivo PKCS12 formatado corretamente:

    // Extrair certificados e chave privada do arquivo .pfx
    openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.crt -nokeys
    openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.key -nodes -nocerts
    
    // Criar novo arquivo PKCS12
    openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx


Como ativar ou desativar

O acesso ao recurso Webhooks está ativado por padrão para contas de plano corporativo.

Administradores de nível de grupo podem criar/controlar apenas os webhooks que operam no grupo.

O acesso à página de webhooks pode ser encontrado no painel esquerdo do menu Administrador: Conta > Webhooks


Ativar um webhook

Quando um webhook é criado pela primeira vez, ele é criado em um status Ativo.

Na página Webhooks no Acrobat Sign, você verá os webhooks ativos por padrão.

Para ativar um webhook inativo:

  • Clique no ícone Opções (três linhas horizontais) à direita da linha de cabeçalho de webhooks e selecione Mostrar todos os webhooks

 

  • Clique uma vez no webhook inativo para selecioná-lo
    • Isso expõe as opções do webhook logo abaixo da linha de cabeçalho
  • Clique em Ativar

O webhook ativo começará a enviar dados para o URL de destino assim que o próximo evento for acionado.


Desativar um webhook

A desativação de um webhook requer apenas que você

  • Navegue até a página Webhooks
  • Clique uma vez no webhook que deseja desativar
  • Selecione Desativar nos itens de menu abaixo da linha de cabeçalho
    • Uma vez desativado, o webhook mostra um status de Inativo


Exibir ou editar um webhook

Os webhooks podem ser editados e salvos a qualquer momento e, ao salvar uma nova configuração, essa alteração entra em vigor imediatamente.

Apenas os Eventos e os Parâmetros de notificação podem ser editados.

Se o Nome, Escopo ou URL precisam ser alterados, um novo webhook terá que ser criado.

Para editar os parâmetros de um webhook:

  • Navegue até a página Webhooks 
  • Clique uma vez no webhook que deseja editar
  • Clique na opção Exibir/Editar abaixo da linha de cabeçalho

 

  • Aplique as alterações necessárias e clique em Salvar


Excluir um webhook

Um webhook pode ser excluído a qualquer momento.

A exclusão de um webhook o destrói no sistema, portanto, não é possível recuperar um webhook excluído.

Os webhooks não precisam ser desativados primeiro.

Para excluir um webhook:

  • Navegue até Webhooks
  • Selecione o webhook que deseja excluir clicando uma vez nele
  • Clique na opção Excluir abaixo da linha de cabeçalho
  • Um desafio é apresentado para garantir que você deseja excluir o webhook. Clique em OK


Práticas recomendadas

  • Seja resistente a duplicidades - se você tiver mais de um aplicativo compartilhando o mesmo URL do webhook e o mesmo usuário mapeado para cada aplicativo, o mesmo evento será enviado para o webhook várias vezes (uma vez por aplicativo). Em alguns casos, o webhook pode receber eventos duplicados. Seu aplicativo de webhook deve ser tolerante a isso e remover as duplicidades por ID de evento.
  • Sempre responder a webhooks rapidamente - seu aplicativo tem apenas dez segundos para responder a solicitações de webhook. Para a solicitação de verificação, isso raramente é um problema, já que seu aplicativo não terá nenhum trabalho de fato para responder. No entanto, para solicitações de notificação, seu aplicativo geralmente fará algo que consome tempo em resposta à solicitação. 

Por exemplo, se você precisar processar e armazenar documentos assinados. Para garantir que você sempre possa responder dentro de dez segundos, você sempre deve fazer seu trabalho em um thread separado ou assincronamente usando uma fila.

  • Gerenciar concorrência - quando um usuário faz várias alterações numa sequência rápida, é provável que o aplicativo receba várias notificações para o mesmo usuário, aproximadamente ao mesmo tempo. Se você não tiver cuidado com o gerenciamento de concorrência, seu aplicativo pode acabar processando as mesmas alterações do mesmo usuário mais de uma vez. 
  • Para aproveitar os webhooks do Acrobat Sign, é necessário entender claramente o uso das informações. Faça perguntas como: 

1. Quais dados você deseja que retornem na carga? 

2. Quem terá acesso a estas informações? 

3. Que decisões ou relatórios serão gerados?

  • Recomendações para recebimento de documento assinado - há vários fatores a serem considerados ao determinar como receber um PDF assinado do Acrobat Sign no sistema de gerenciamento de documentos. 

Embora seja perfeitamente aceitável apenas selecionar a opção Documento assinado do contrato ao criar um webhook, você pode considerar o uso da API do Acrobat Sign para recuperar os documentos quando um evento de acionamento (como status de contrato concluído) é recebido.


Itens a serem considerados...

Limitação de tamanho JSON

O tamanho da carga JSON é limitado a 10 MB.

Se um evento gerar uma carga maior, um webhook será acionado, mas os atributos do parâmetro condicional, se houver na solicitação, serão removidos para reduzir o tamanho da carga. 

"ConditionalParametersTrimmed " será retornado na resposta quando isso acontecer para informar ao cliente que o  conditionalParameters  As informações foram removidas.

conditionalParametersTrimmed” é um objeto de matriz que contém as informações sobre as chaves que foram cortadas.

O truncamento será feito na seguinte ordem:

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

Os documentos assinados serão truncados primeiro, seguidos pelas informações do participante, informações do documento e, por fim, as informações detalhadas.

Isso pode acontecer, por exemplo, em um evento de conclusão de contrato, se este incluir um documento assinado (com codificação Base64), ou em um contrato com vários campos de formulário


Notificações do webhook

Os webhooks do Acrobat Sign entregam notificações que são aplicáveis a todos os participantes de um contrato se houver um webhook configurado para esse usuário, seu grupo ou sua conta.

Os eventos do contrato são processados de forma que, se houver um webhook configurado para o participante aplicável desse evento, uma notificação será enviada para o URL desse webhook. Em outras palavras, webhooks são acionados para eventos em todos os contratos aplicáveis, mesmo aqueles fora do grupo ou da conta na qual o webhook está configurado.

As notificações são entregues apenas para os eventos com os quais o participante está envolvido. Por exemplo, o Remetente de um contrato recebe quase todas as notificações, enquanto os Destinatários recebem notificações apenas a partir do início da sua participação no acordo e somente dos eventos em que estão envolvidos.

As notificações do webhook seguem o modelo atual de autenticação e visibilidade do Acrobat Sign, o que significa que os usuários terão acesso ao contrato somente quando a participação do usuário em um contrato tiver sido iniciada.

O Remetente envia um contrato para assinatura a três signatários.

  • Há um WebhookX de nível de conta configurado para a conta dos Remetentes.
  • O Signatário1 é um membro da mesma conta que o remetente, mas em um grupo diferente, e há um WehbhookY configurado para esse grupo.
  • O Signatário2 é um membro de uma conta diferente. Há um WebhookZ de nível de conta configurado para a conta do Signatário2.
  • O Signatário3 é um membro da mesma conta que um remetente.

O Remetente envia um contrato: o WebhookX é acionado em “Contrato criado” e “Contrato enviado”, enquanto o WebhookY é acionado em “Contrato enviado”.

O Signatário1 assina: o WebhookX é acionado em “Participação no contrato concluída” e “Contrato enviado”, o WebhookY é acionado em “Participação no contrato concluída” e o WebhookZ é acionado em “Contrato enviado”.

O Signatário2 assina: o WebhookX é acionado em “Participação no contrato concluída” e “Contrato enviado”, enquanto o WebhookZ envia a notificação “Participação no contrato concluída”.

O Signatário3 assina: o WebhookX é acionado em “Participação no contrato concluída” e “Fluxo de trabalho do contrato concluído”, o WebhookY é acionado em “Fluxo de trabalho do contrato concluído” e o WebhookZ é acionado em “Fluxo de trabalho do contrato concluído”.


Tentar novamente quando o serviço de escuta estiver inativo

Se o URL de destino do webhook estiver inativo por algum motivo, o Acrobat Sign enfileira o JSON e tenta executar novamente o push em um ciclo progressivo ao longo de 72 horas.

Os eventos não entregues são persistidos em uma fila de tentativas e é feito um melhor esforço nas 72 horas seguintes para entregar as notificações na ordem em que ocorreram.

A estratégia para repetir a entrega de notificações é duplicar o tempo entre tentativas, começando com um intervalo de um minuto e aumentando para a cada 12 horas, resultando em 15 tentativas em 72 horas.

Se o receptor do webhook não responder dentro de 72 horas e não houver entregas de notificação bem-sucedidas nos últimos sete dias, o webhook será desativado. Nenhuma notificação será enviada para este URL até que o webhook seja ativado novamente.

Todas as notificações entre o momento em que o webhook é desativado e ativado novamente serão perdidas.

Logotipo da Adobe

Fazer logon em sua conta