Webhook de assinatura eletrônica: como acompanhar documentos

Um contrato pode estar assinado na Assinafy e continuar como pendente no sistema da empresa. Para conectar essas duas informações, o webhook de assinatura eletrônica envia uma notificação ao endereço configurado pela equipe quando um evento selecionado acontece. O sistema que recebe essa mensagem pode usá-la para atualizar um registro ou iniciar uma tarefa, conforme as regras da integração.

A diferença está em quem inicia a comunicação: em vez de consultar repetidamente se algo mudou, a aplicação recebe o aviso do acontecimento. Isso ajuda a organizar o acompanhamento, mas receber o webhook e concluir uma atualização no CRM são resultados distintos. Você precisa definir qual evento interessa, como reconhecer o documento e quem responde por uma falha no processamento.

Este guia apresenta o funcionamento documentado dos webhooks da Assinafy e os critérios para planejar seu uso na operação. O objetivo é ajudar a escolher eventos e controles, sem apresentar uma implementação específica como integração já homologada.

O que o webhook informa ao seu sistema

Webhook é uma chamada que um serviço envia a outro quando ocorre um evento. Na Assinafy, o endereço receptor recebe uma requisição HTTP POST com dados em JSON, um formato de troca de informações entre sistemas. A mensagem identifica o acontecimento e traz informações relacionadas a ele, conforme o contrato daquele evento.

Pense em uma empresa que envia contratos de prestação de serviços e acompanha o andamento em uma aplicação própria. Quando um signatário assina, o aviso pode alimentar o acompanhamento individual; quando o último assina, outro evento permite reconhecer esse marco do documento. A ação posterior, como liberar uma conferência interna, depende do que a empresa implementou no sistema receptor.

Essa ligação complementa a API de assinatura eletrônica: a API permite que a aplicação faça solicitações, enquanto o webhook avisa sobre acontecimentos para os quais o endereço foi inscrito. Os dois mecanismos podem participar do mesmo fluxo, com papéis diferentes.

O conteúdo recebido também exige interpretação. Um evento registra um acontecimento em determinado momento; não representa, sozinho, uma fotografia atual de todos os sistemas envolvidos. Se o processamento acontecer depois, a integração precisa avaliar o contexto antes de alterar um registro que já avançou.

Escolha o evento pela decisão operacional

Antes de ativar eventos, escreva a pergunta que sua equipe precisa responder. “Quem ainda não assinou?” pede acompanhamento por signatário; “todos já assinaram?” pede um marco do documento. Usar o mesmo tratamento para essas perguntas pode liberar uma etapa antes da hora ou esconder uma pendência individual.

A documentação da Assinafy distingue, entre outros, estes eventos:

Evento	Acontecimento documentado	Como interpretar na operação
`document_metadata_ready`	O documento foi normalizado para PDF e suas páginas estão disponíveis.	É um marco de preparação, não de assinatura.
`document_prepared`	O documento foi preparado, com campos atribuídos aos signatários.	A preparação avançou; isso não comprova que alguém assinou.
`signer_signed_document`	Um signatário assinou o documento.	Atualize o acompanhamento daquela participação.
`document_ready`	O último signatário assinou e o status do documento passou para `ready`.	Reconheça o marco de todas as assinaturas, separando etapas posteriores.
`signer_rejected_document`	Um signatário recusou assinar.	Encaminhe a ocorrência conforme a regra de exceção da empresa.
`user_rejected_document`	Um usuário da conta cancelou o documento.	Diferencie cancelamento pela equipe de recusa pelo signatário.
`document_processing_failed`	O processamento do documento falhou.	Investigue a falha antes de continuar a preparação.

Essa seleção ilustra diferenças importantes; não substitui o catálogo completo da API. Na configuração, escolha os eventos que sustentam ações reais e atribua um responsável a cada exceção relevante. Ativar notificações sem definir o que fazer com elas pode apenas aumentar o volume de mensagens recebidas.

Considere um contrato com duas pessoas que precisam assinar. O primeiro `signer_signed_document` não basta para marcar o documento inteiro como concluído no sistema da empresa. Da mesma forma, `document_ready` não comprova que o arquivo foi baixado, armazenado ou associado ao registro comercial: essas são tarefas posteriores da integração. O status `ready` também não equivale, por si, à disponibilidade do arquivo certificado.

Onde configurar e acompanhar na Assinafy

Na Assinafy, a configuração fica em Configurações do Workspace, na aba Webhooks. O percurso documentado inclui ativação, endereço do sistema que receberá os eventos, e-mail para notificações importantes e seleção dos eventos. A equipe deve conferir o workspace escolhido antes de salvar, porque a configuração precisa corresponder à operação que está sendo acompanhada.

O endereço receptor é a aplicação que vai receber e tratar as chamadas. Informar a URL de uma página comum não cria esse tratamento automaticamente; é necessário que exista um serviço preparado para essa finalidade. O responsável técnico deve verificar o contrato de recebimento e o acesso ao ambiente apropriado.

A API também documenta operações para administrar endpoints, que são os endereços receptores cadastrados, e consultar o histórico de entregas. Cada endpoint tem sua URL, seleção de eventos e configuração de assinatura. Uma integração que administra vários destinos precisa identificar qual endpoint está sendo consultado ou alterado.

A aba Logs de Webhooks é descrita como o histórico de disparos, com nome do evento, data de envio e situação da entrega. Essa consulta ajuda a investigar se a notificação saiu da plataforma e como a entrega foi registrada. Para descobrir se a atualização comercial terminou, consulte também os registros do sistema receptor.

Se a equipe usa uma integração pronta ou uma ferramenta de automação, confirme quem administra o endereço e os registros de processamento. A existência de um conector não significa que qualquer evento ou regra da empresa esteja configurado nele. A escolha entre conector e integração própria depende do percurso necessário e do que o conector ou a API efetivamente suporta.

Como acompanhar assinaturas com ferramentas de automação

Você pode usar ferramentas de automação de processos para receber eventos e organizar as próximas etapas, sem desenvolver um receptor próprio do zero. No n8n, o pacote da comunidade da Assinafy inclui o Assinafy Trigger, que cadastra o endereço de recebimento ao ativar o workflow e permite selecionar os eventos acompanhados.

Entre os eventos disponíveis estão:

• signer_signed_document: assinatura de um signatário.
• document_ready: marco de todas as assinaturas.
• signer_rejected_document: recusa de um signatário.
• document_processing_failed: falha no processamento do documento.

Essa escolha permite separar avanço individual, conclusão das assinaturas e situações que pedem intervenção.

Um fluxo pode receber document_ready e encaminhar uma tarefa de conferência para o sistema usado pela empresa, desde que a ação de destino esteja configurada. O evento inicia o fluxo; a confirmação de que a tarefa terminou deve ser acompanhada no próprio workflow e no sistema de destino. Para baixar o arquivo certificado, é necessário conferir sua disponibilidade, pois document_ready não garante que ele já esteja pronto.

Esse caminho ainda exige instalar o pacote em uma instância compatível do n8n, configurar a credencial de API da Assinafy e selecionar os eventos. A publicação do pacote não garante sua disponibilidade no n8n Cloud. A vantagem é aproveitar o gatilho e as ações disponíveis para montar a automação, mantendo a responsabilidade pela configuração, pelos acessos e pelo tratamento de falhas.

Receber o aviso e concluir a tarefa são etapas diferentes

No contrato documentado, uma resposta HTTP da família 2xx é considerada sucesso da entrega do webhook. Esse reconhecimento informa que o receptor aceitou a chamada; não demonstra, por si, que todas as ações posteriores terminaram. A integração precisa manter evidência do trabalho que assume realizar.

Uma forma de organizar a automação de processos é separar recebimento, processamento e resultado. Primeiro, o receptor verifica a mensagem e registra o que recebeu; depois, executa a ação correspondente. Por fim, registra se a atualização no sistema de destino foi concluída ou ficou pendente.

Essa separação é uma recomendação de arquitetura para a aplicação da empresa. Por exemplo, a equipe pode decidir registrar de maneira durável o trabalho antes de confirmar seu recebimento. O desenho precisa considerar o que acontece se o processo parar entre essa confirmação e a atualização do destino.

Imagine que o aviso de todas as assinaturas seja recebido, mas o CRM fique indisponível durante a atualização. O documento não precisa ser enviado novamente para assinatura apenas porque essa tarefa falhou. A recuperação deve partir do documento existente e da atualização pendente, com uma regra para evitar repetir o efeito comercial.

Verifique a origem e valide o conteúdo

A API documenta assinatura criptográfica para endpoints com essa opção habilitada. Nesse caso, a entrega inclui os cabeçalhos `webhook-id`, `webhook-timestamp` e `webhook-signature`. A verificação utiliza o segredo do endpoint e o corpo original da requisição, exatamente como foi recebido.

O corpo original importa porque a assinatura considera seus bytes. Interpretar o JSON e depois remontá-lo, mudando espaços ou a representação dos campos, pode produzir um conteúdo diferente para a conferência. A equipe deve seguir a documentação técnica atual ao escolher a biblioteca ou o verificador da integração. A conferência também precisa avaliar a validade temporal de `webhook-timestamp`, conforme o contrato, para rejeitar mensagens fora da janela aceita.

A verificação de origem não substitui a validação dos dados necessários à tarefa. Depois dessa conferência, o receptor ainda precisa reconhecer o tipo de evento, identificar a entidade correta e verificar se ela pertence ao contexto esperado. A estrutura varia conforme o evento: não é seguro tratar qualquer objeto recebido como se descrevesse sempre um documento com os mesmos campos.

Também é necessário cuidar do segredo do endpoint. Ele deve ficar na configuração protegida do serviço que recebe as mensagens, sem aparecer em prompts, planilhas de pauta, imagens ou registros públicos. A documentação de API orienta a equipe a consultar o contrato específico, em vez de deduzir autenticação pelo nome de um campo.

A assinatura não está implícita em qualquer webhook cadastrado: a documentação a relaciona à opção de assinatura do endpoint. Confirme essa configuração e o mecanismo disponível no seu percurso. Um tutorial de código deve validar esse caminho no ambiente declarado antes de apresentar uma implementação como pronta.

Trate repetição, atraso e falha de entrega

O contrato da API informa que `webhook-id` se mantém nas tentativas do mesmo evento para o mesmo endpoint. Esse identificador é indicado para reconhecer repetição de entrega. Um receptor que usa essa informação pode registrar que aquela mensagem já foi aceita e evitar executar novamente a mesma tarefa.

Esse controle precisa sobreviver ao reinício do serviço. Guardar identificadores apenas na memória não mantém o histórico quando o processo é encerrado. A equipe deve escolher persistência, regra de retenção e tratamento de concorrência compatíveis com a operação, sem confundir a verificação criptográfica com deduplicação.

Um evento atrasado exige outro cuidado. Se a aplicação já conhece uma situação mais recente, processar uma notificação anterior como se ela fosse o estado atual pode fazer o registro regredir. Avaliar a data do acontecimento e, quando necessário, consultar o documento ajuda a definir uma regra de atualização adequada.

A documentação também prevê retentativa de entrega e uma operação de retry manual pela API. Isso não elimina a necessidade de acompanhar falhas, nem autoriza assumir que toda mensagem será entregue indefinidamente. Quando houver dúvida sobre uma regra não descrita ou divergência entre fontes, o ponto deve ser confirmado com Produto antes de virar promessa no fluxo da empresa.

Para a operação, defina quem acompanha mensagens não entregues e quem acompanha tarefas internas pendentes. São filas diferentes: uma trata da comunicação com o receptor; a outra, do processamento que ele assumiu. O processo precisa permitir reconhecer e retomar cada situação sem reenviar o contrato desnecessariamente.

Mantenha o vínculo entre evento, documento e registro

O acompanhamento perde utilidade quando a equipe recebe uma mensagem correta, mas não sabe a qual contrato ela pertence. Na gestão de documentos, o vínculo entre identificadores técnicos e registros de negócio precisa ser planejado desde a criação ou associação do documento.

A aplicação pode manter a relação entre workspace, documento e registro comercial para localizar o destino de uma atualização. Essa é uma responsabilidade da integração, não uma associação universal que todo webhook cria automaticamente. O conteúdo e os identificadores disponíveis devem ser conferidos no contrato do evento escolhido.

Preserve também a diferença entre histórico operacional e trilha de auditoria. O primeiro explica o que a integração recebeu e conseguiu processar; a trilha do documento registra os acontecimentos relacionados ao seu percurso de assinatura. Um log interno não substitui as evidências do documento, e a existência dessas evidências não comprova que o CRM foi atualizado.

No cenário de uma empresa de serviços, pode haver um documento para a proposta e outro para o contrato. Associar ambos apenas pelo nome do cliente cria ambiguidade. Definir a relação por identificadores e pelo tipo de registro evita que um evento atualize a etapa errada do processo comercial.

Defina os critérios antes de ativar a automação

O desenho deve começar pela ação esperada. Especifique o evento, o registro afetado, a mudança permitida e o comportamento diante de repetição ou falha. A equipe consegue revisar uma regra como “ao reconhecer todas as assinaturas, abrir a tarefa de conferência do documento” com mais precisão do que uma instrução genérica para concluir a venda.

A aprovação interna também precisa permanecer distinta da assinatura. Um workflow de aprovação de documentos pode estabelecer quem confere conteúdo e condições antes do envio. O webhook informa os eventos para os quais foi configurado, sem decidir sozinho se a negociação está aprovada ou se todas as condições comerciais foram cumpridas.

Antes de colocar uma implementação em produção, o responsável técnico deve validar o percurso escolhido, incluindo origem da mensagem, identificação, repetição e recuperação. Este guia descreve mecanismos documentados e recomendações de organização; a verificação da integração concreta depende do receptor, do ambiente e da regra implementada.

Para começar pelo produto, conheça a Assinafy e crie uma conta grátis. Se a decisão envolver recursos e condições de contratação, consulte os planos da Assinafy antes de configurar a operação. A escolha de plano e de integração deve corresponder às necessidades da sua empresa.