Guia do Usuário Cancelar

Configurar webhooks

Visão geral

Um webhook é uma solicitação HTTPS definida pelo usuário que é acionada quando um evento inscrito ocorre no site de origem (neste caso, o Adobe Acrobat Sign).

Basicamente, um webhook é um serviço REST que aceita dados ou um fluxo de dados.

Os webhooks são destinados para comunicação serviço a serviço em um modelo de PUSH.

Quando um evento inscrito é acionado, 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 de callback anterior, entre eles:

  • Os administradores podem ativar seus webhooks sem precisar envolver o suporte do Acrobat Sign para listar o URL do callback
  • Os webhooks oferecem dados mais atualizados, mais 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 de aplicativos modernos
  • Vários webhooks podem ser configurados por escopo (Conta/Grupo/Usuário/Recurso), enquanto os callbacks precisavam ser exclusivos
  • Os webhooks permitem selecionar os 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 acionamento do webhook para eventos de Contrato, Formulário web (Widget) ou Envio em massa (MegaSign). O recurso Modelo de biblioteca (Documento da biblioteca) também pode ser configurado por meio da API.

O escopo do webhook pode incluir a conta inteira ou grupos individuais por meio da interface do administrador. A API permite mais granularidade por meio da seleção dos escopos USUÁRIO ou RECURSO.

O tipo de dados que é enviado ao URL é configurável e pode incluir itens como informações do contrato, do participante, do documento e assim por diante.

Depois que o webhook é configurado e salvo, o Acrobat Sign envia um novo objeto JSON ao URL definido sempre que o evento inscrito é acionado. 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 sucesso, 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 o Acrobat Sign recebe uma nova solicitação de registro de webhook, 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 desse 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 sucesso, o URL do webhook deve responder a essa solicitação de verificação com um código de resposta 2XX E, além disso, ele DEVE enviar de volta o mesmo valor de ID de cliente de uma de duas maneiras:

  • Em um cabeçalho de resposta X-AdobeSign-ClientId. Esse é o mesmo cabeçalho transmitido na solicitação e repetido na resposta.
  • Ou 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, ele não responderá 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 da resposta de sucesso e o Acrobat Sign cuidará para 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 que a notificação do webhook foi entregue com êxito 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 por meio de um corpo de resposta JSON que contém xAdobeSignClientId como chave e a mesma ID de cliente como valor. Caso contrário, tentaremos enviar a notificação novamente para o URL do webhook até que as tentativas sejam esgotadas.

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 - Qual é o alcance de 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 pode ser definido por webhook.
  • URL - O URL de destino para o qual o Acrobat Sign enviou o conteúdo JSON.
  • Eventos - O acionador que faz com que o Acrobat Sign crie o JSON e o envie para o URL.
    • Cada evento cria um conteúdo diferente que seja 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 conteúdo JSON do evento, permitindo que você selecione apenas as seções do evento que são importantes para este webhook (reduzindo assim o número de dados desnecessários enviados para 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 da conta têm autoridade para ver todos os webhooks definidos para a conta e todos os grupos dentro dela.
  • Grupo: todos os eventos inscritos que ocorrem no grupo acionam o push. OBSERVAÇÃO: Os webhooks com escopo de grupo existem apenas para esse grupo.
    • Os administradores do grupo verão apenas os webhooks dedicados ao seu grupo. Eles não podem ver os webhooks no nível da conta ou webhooks vinculados a outros grupos.
    • As contas com a opção Usuários em vários grupos ativada verão a opção de selecionar 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 no nível do recurso só podem ser criados por meio da 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 ponto de acesso do URL deve estar acompanhando a porta 443 ou 8443 (isso é decidido pelo cliente ao definir o URL do callback).
  • 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 por objeto e listados na ordem em que são encontrados na interface.

O valor à esquerda é o valor que você verá na interface do Acrobat Sign. O valor à direita é o nome do webhook na API.

Para obter detalhes completos sobre os webhooks e seus conteúdos, consulte o Guia dos desenvolvedores do Acrobat Sign.

Contratos:

Elemento de interface Nome do webhook
Todos os eventos do contrato AGREEMENT_ALL
Contrato criado AGREEMENT_CREATED
Contrato enviado AGREEMENT_ACTION_REQUESTED
Participação no contrato concluída AGREEMENT_ACTION_COMPLETED
Fluxo de trabalho do contrato concluído AGREEMENT_WORKFLOW_COMPLETED
O contrato expirou AGREEMENT_EXPIRED
Contrato excluído AGREEMENT_DOCUMENTS_DELETED
Contrato cancelado AGREEMENT_RECALLED
Contrato rejeitado AGREEMENT_REJECTED
Contrato compartilhado AGREEMENT_SHARED
O contrato foi delegado AGREEMENT_ACTION_DELEGATED
Participante do contrato substituído AGREEMENT_ACTION_REPLACED_SIGNER
Contrato modificado AGREEMENT_MODIFIED
Modificação no contrato reconhecida AGREEMENT_USER_ACK_AGREEMENT_MODIFIED
Email do contrato visualizado AGREEMENT_EMAIL_VIEWED
O email do contrato retornou AGREEMENT_EMAIL_BOUNCED
Falha na criação do contrato AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
Contrato sincronizado pós evento offline AGREEMENT_OFFLINE_SYNC
Upload do contrato feito pelo remetente AGREEMENT_UPLOADED_BY_SENDER
Contrato arquivado AGREEMENT_VAULTED
Identidade social do participante do contrato autenticada AGREEMENT_WEB_IDENTITY_AUTHENTICATED
KBA do participante do contrato autenticado AGREEMENT_KBA_AUTHENTICATED
Lembrete de contrato enviado AGREEMENT_REMINDER_SENT
Nome do signatário do contrato alterado pelo signatário AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER
   
O contrato dos Webhooks está disponível somente via API
N/A AGREEMENT_EXPIRATION_UPDATED
N/A
AGREEMENT_READY_TO_NOTARIZE
N/A
AGREEMENT_READY_TO_VAULT

 

Envio em massa:

Elemento de interface Nome do webhook
Enviar em massa todos os eventos MEGASIGN_ALL
Enviar em massa os criados
MEGASIGN_CREATED
Enviar em massa os compartilhados
MEGASIGN_SHARED
Enviar em massa os recuperados
MEGASIGN_RECALLED

 

Formulários Web:

Elemento de interface Nome do webhook
Fazer formulário Web de todos os eventos WIDGET_ALL
Formulário Web criado
WIDGET_CREATED
Formulário Web habilitado
WIDGET_ENABLED
Formulário Web desabilitado
WIDGET_DISABLED
Formulário Web modificado
WIDGET_MODIFIED
Formulário Web compartilhado
WIDGET_SHARED
Falha na criação do formulário Web
WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM

 

Modelos de biblioteca (somente API):

Elemento de interface Nome do webhook
N/A LIBRARY_DOCUMENT_ALL
N/A LIBRARY_DOCUMENT_CREATED
N/A LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
N/A LIBRARY_DOCUMENT_MODIFIED

 

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 Substituição do participante do contrato, 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 do JSON enviado ao 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 aos eventos Fluxo de trabalho do contrato concluído 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 dispositivo : 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 dispositivo — 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 falharem na verificação de certificado SSL não entregarão a carga JSON com sucesso. 

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

Verificação de certificado de cliente

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

  • Inscreva-se em eventos específicos e necessários para limitar o número de solicitações HTTPS ao servidor - quanto mais específicos forem seus webhooks, menor será o volume necessário para examinar.
  • 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 responda 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. É recomendável trabalhar em um thread separado ou de forma assíncrona usando uma fila para garantir que você possa responder dentro de cinco segundos
  • 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: 
    • Quais dados você deseja que retornem na carga? 
    • Quem terá acesso a estas informações? 
    • Que decisões ou relatórios serão gerados?
  • Recomendações para recebimento de um 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 as informações de  conditionalParameters  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.

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.

Receba ajuda com mais rapidez e facilidade

Novo usuário?