Webhook de assinatura eletrônica: do evento recebido ao estado confirmado

Um webhook avisa ao seu sistema que algo aconteceu em um fluxo de assinatura. Seu backend recebe uma requisição HTTP, registra o evento e consulta o estado atual do envelope antes de liberar a próxima etapa. Essa separação ajuda a não tratar um aviso, uma duplicata ou uma entrega atrasada como confirmação suficiente para a próxima etapa.

Para montar uma integração, a API cria e consulta recursos; o webhook avisa quando vale consultar. Na documentação da API v4 da SuperSign, o fluxo começa pela criação do envelope, definição dos participantes e envio do documento. A parte de eventos entra quando seu sistema precisa reagir sem ficar perguntando repetidamente se alguém já assinou.

API e webhook fazem trabalhos diferentes

A chamada à API parte do seu sistema: criar envelope, enviar, consultar estado. O webhook parte da plataforma de assinatura: uma notificação é enviada à URL cadastrada por você. Receber SIGNATORY_SIGNED indica um ato de um participante; ENVELOPE_COMPLETED indica conclusão do fluxo do envelope segundo a documentação. Isso não determina, sozinho, efeitos jurídicos ou financeiros.

Pense num CRM. Depois que a equipe envia um contrato, o CRM pode mostrar “aguardando assinaturas”. Quando recebe um aviso, ele não precisa assumir que o documento está finalizado. Primeiro registra o evento; depois consulta o envelope e só muda para “concluído” se o estado confirmado corresponder à regra de negócio. Se o webhook chegar novamente, o registro do mesmo evento não deve repetir o trabalho.

O que um receptor precisa fazer

1. Cadastre uma URL HTTPS de seu backend para os eventos necessários. Revise quem pode administrar o endpoint e quais envelopes da conta ele cobre; na documentação da SuperSign, webhooks são de escopo da conta, não apenas da pasta visível à chave que criou o endpoint.
2. Confira a autenticidade da entrega conforme a documentação de teste e verificação e preserve o corpo original para verificar a assinatura. Não aceite qualquer POST que apenas tenha um campo event.
3. Se o contrato da API fornecer um identificador estável para o evento, registre-o com restrição de unicidade antes de confirmar a recepção. Uma entrega repetida não deve refazer o processamento. Proteja também a ação de negócio por uma chave própria: dois eventos diferentes podem tentar executar a mesma ação sobre o mesmo envelope.
4. Devolva sucesso HTTP apenas depois da aceitação durável do evento. Se a gravação falhar, deixe o provedor tratar a tentativa como falha, conforme a política documentada, em vez de perder o aviso em memória.
5. Processe em uma fila ou tarefa separada, com tentativas próprias em caso de falha. Consulte GET /v4/api/envelopes/{envelopeId} com permissão adequada, confira o estado e só então atualize o seu sistema. Se a consulta falhar após o receptor responder 2xx, mantenha a tarefa pendente e tente novamente: o provedor não recupera um processamento interno já confirmado como recebido. Não exponha identificadores e dados de pessoas em logs públicos.

Esses passos descrevem a arquitetura de um receptor, não um código pronto para copiar. Regras de autenticação, retentativa, formato de payload e permissões podem evoluir. Antes de implementar, confira o guia atual de teste no Sandbox e a referência da API.

E se a entrega falhar ou vier fora de ordem?

Não dependa da ordem de chegada como verdade de negócio. Trate como possível que um evento antigo chegue depois de outro mais recente. Guarde o evento e consulte o estado atual do envelope antes de executar a ação. Para tarefas sensíveis, como liberar um serviço ou solicitar faturamento, registre a decisão aplicada, o estado consultado e o horário da consulta.

Se o endpoint não responder corretamente, investigue a entrega e o resultado HTTP. A documentação da SuperSign descreve consulta às entregas e opção de reenviar as que falharam ou foram ignoradas. Um reenvio entrega novamente o evento ao receptor; seu sistema não deve executar outra vez a mesma ação comercial para aquele envelope e finalidade. Evite publicar URLs temporárias de download, chaves ou o corpo de um evento real em tickets de suporte.

Como testar sem afetar clientes

Antes de começar, confirme que sua conta tem acesso ao ambiente de testes (Sandbox). Cadastre um endpoint de teste, use o evento de teste documentado para verificar a recepção e depois crie um envelope com dados fictícios, sem dados de clientes. Exercite ao menos quatro situações: entrega aceita, erro do receptor, evento duplicado e consulta de um estado ainda não concluído. Confirme o que o seu sistema gravou, não apenas o status da requisição de teste.

O Sandbox é ambiente de desenvolvimento, não substitui a validação do fluxo e das condições de produção. Se a sua equipe usa n8n ou outra ferramenta de automação, confira se o receptor consegue registrar a entrega de modo durável antes de responder sucesso. Quando não conseguir, coloque um backend ou serviço intermediário responsável por isso.

Perguntas rápidas

Um webhook traz o PDF assinado?

Não trate o evento como arquivo final. Consulte as rotas de documento e download previstas na documentação, com as permissões necessárias, depois de verificar o estado. A política de armazenamento e retenção do seu lado deve ser definida pela empresa.

Receber SIGNATORY_SIGNED permite faturar?

Não por si só. Pode haver outros participantes ou uma regra contratual específica. Confirme o estado do envelope e aplique os critérios comerciais e contratuais aprovados pela equipe antes de iniciar uma ação financeira.

Preciso fazer polling mesmo com webhook?

O webhook reduz consultas repetidas. Uma consulta pontual para confirmar o estado após o evento continua útil. Também é prudente prever reconciliação controlada de falhas, sem transformar o sistema numa consulta contínua sem limite.

Próximo passo

Para o fluxo de envelopes, consulte a introdução técnica à API v4. Para a recepção dos eventos, leia o guia de teste dos webhooks. Se precisar avaliar acesso e condições da conta, veja a página comercial da API ou fale com a equipe. Não envie credenciais nem documentos de clientes pelo formulário.

Este guia foi útil? Compartilhe com quem precisa: LinkedIn · WhatsApp.