ENVELOPE_COMPLETED e a API pública. Serve para quem monta o fluxo no n8n, no Zapier ou no Make, e também para quem prefere escrever um pequeno serviço em Node.ENVELOPE_COMPLETED.2xx e guarda o evento.ss_live_. Visão geral dos webhooks em Webhooks.403 API_NOT_IN_PLAN).ss_live_ com os escopos certos. Para cadastrar o endpoint, a chave precisa de webhooks:write. Para baixar os documentos, o fluxo precisa de envelopes:read. O ideal é usar duas chaves: uma administrativa, só para cadastrar o endpoint, e outra só com envelopes:read dentro do n8n, Zapier ou Make. Se a chave de download vazar, ela só lê. Veja Escopos da chave.404 RESOURCE_NOT_FOUND. Para guardar tudo da conta, emita a chave de download pelo proprietário da conta (papel OWNER).ss_test_ e https://api.sandbox.supersign.com.br. Em produção a base é https://api.sign.supersign.com.br.201 traz o signingSecret (whsec_...) uma única vez. Guarde-o num cofre de segredos. Se perder, gire o segredo (veja Girar o segredo de assinatura). A URL precisa ser HTTPS, na porta 443, em host público (veja Requisitos da URL).ENVELOPE_COMPLETED{
"id": "9d4fb916-5ab7-4a49-9014-1249345f1c6c",
"event": "ENVELOPE_COMPLETED",
"createdAt": "2026-09-03T18:30:00.000Z",
"data": {
"envelope": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "COMPLETED",
"completedAt": "2026-09-03T18:29:58.000Z"
},
"documents": [
{
"id": "2f1c5d8d-97dd-40a8-aefe-1eec9d17e301",
"name": "contrato.pdf",
"originalFileHash": "4f6f53d15ea7ed8cb002f85d2cb1f6c0f2bd5861d89fc3f9f30670ecf40cb3d2",
"sealedFileHash": "9b2e6c0a1d4f8e3b7a5c2d9f0e1b4a6c8d3f5e7a9b1c2d4e6f8a0b3c5d7e9f1a"
}
],
"signatories": []
}
}| Campo | Para que serve |
|---|---|
id | Id do evento. É a chave para deduplicar entregas repetidas. |
data.envelope.id | Id do envelope. Boa chave para a pasta no seu Drive. |
data.documents[].id | Id do documento. É o que vai na rota de download. |
data.documents[].name | Nome original do arquivo. Use para nomear a cópia. |
data.documents[].sealedFileHash | SHA-256 do PDF selado, para conferir o que você baixou. |
environment não existe; na Sandbox ele vale "sandbox".X-SuperSign-Signature: t=1700000000,v1=<hex>t é o horário do disparo, em segundos (epoch).v1 é HMAC-SHA256(segredo, "<t>.<corpo cru>"), em hexadecimal.|agora - t| passar de 5 minutos e compare em tempo constante. O detalhe completo e o exemplo em Python estão em Segurança e verificação.{ "url": "https://storage.googleapis.com/..." }GET /v4/api/documents/{documentId}/download. O parâmetro type é obrigatório: signed (assinado) ou original.envelopes:read.url. Ela é temporária, assinada, e vale por 15 minutos.GET simples na url, sem o cabeçalho Authorization. Não grave a URL em log nem em planilha.signed.{ "url": "...", "expiresAt": "2026-09-03T18:31:00.000Z", "fileName": "..." }GET /v4/api/envelopes/{envelopeId}/download, com tipo=assinados (padrão) ou tipo=originais. Escopo envelopes:read.url do ZIP vale para um único download e expira em 60 segundos. Pedir de novo a mesma URL é recusado. Peça e baixe na sequência, sem guardar a URL.type=signed já traz esse certificado. A API pública não tem uma rota separada para o certificado.documents[].sealedFileHash do evento. Se vier null, o selado não tem hash registrado (documento legado) e a conferência não é possível. Se divergir, descarte, não grave no Drive e tente de novo.2xx logo. O trabalho pesado (baixar e gravar) roda num worker. As funções fila e salvarNoDrive são pontos de extensão seus:| # | Nó | Configuração |
|---|---|---|
| 1 | Webhook | Método POST. Em Options, ligue Raw Body. Em Respond, escolha Using 'Respond to Webhook' Node. Cadastre a URL de produção desse nó no passo 1. |
| 2 | Code (verificar) | Lê o corpo cru e o cabeçalho x-supersign-signature, recalcula o HMAC e falha o fluxo se não conferir (código abaixo). Em n8n self-hosted, libere NODE_FUNCTION_ALLOW_BUILTIN=crypto. |
| 3 | IF | event igual a ENVELOPE_COMPLETED. Qualquer outro evento vai direto para o nó 5. |
| 4 | Data table ou Postgres | Insere id do evento com chave única. Se já existir, é duplicata: siga para o nó 5 sem baixar de novo. |
| 5 | Respond to Webhook | Código 200. Responda antes de baixar os arquivos, para ficar dentro do prazo de 20 segundos. |
| 6 | Split Out | Campo data.documents, um item por documento. |
| 7 | HTTP Request (pedir URL) | GET https://api.sign.supersign.com.br/v4/api/documents/{{ $json.id }}/download?type=signed. Autenticação: credencial Header Auth com Authorization: Bearer <chave envelopes:read>. Ligue Retry on Fail e, em Batching, limite a vazão (veja Limites). |
| 8 | HTTP Request (baixar PDF) | GET {{ $json.url }}, sem autenticação, Response Format File. |
| 9 | Google Drive | Operação Upload. Pasta de destino: seu folderId. Nome: {{ $('Split Out').item.json.name }}. |
X-SuperSign-Signature se a ferramenta der acesso ao corpo cru, responda 2xx, peça a URL com um passo de HTTP e grave o arquivo no Drive. Se a ferramenta não der acesso ao corpo cru, use um receptor intermediário (como o exemplo em Node) e deixe só o upload na ferramenta.2xx rápido, somente depois de guardar o evento. A tentativa tem prazo de 20 segundos.403, 404, 408, 425, 429 e qualquer 5xx geram nova tentativa. Redirecionamentos e os demais 4xx (como 401 e 410) não são retentados.FAILED e pode ser reenviada por POST /v4/api/webhooks/{webhookId}/deliveries/{deliveryId}/retry.id. Deduplique pelo id do evento.ENVELOPE_COMPLETED com id de evento novo, o mesmo data.envelope.id e um sealedFileHash novo. A deduplicação pelo id do evento não pega esse caso, e isso é o certo: você quer a versão nova. Grave por cima do arquivo do mesmo documento (mesma pasta e mesmo nome) em vez de criar uma segunda cópia, e confira o hash novo. O hash antigo deixa de conferir na verificação pública.2xx rápido e baixe depois. Baixar PDF dentro do request estoura o prazo e provoca retentativa.id do evento com uma chave única. Marque o evento como concluído só depois do upload, para poder retomar após uma falha.GET /v4/api/envelopes/{envelopeId} deve mostrar COMPLETED.sealedFileHash.whsec_ nem as URLs temporárias de download. O payload tem nome, e-mail e telefone de participantes: proteja logs, filas e o destino.2xx a eventos que você não conhece. Novos tipos podem ser adicionados.ss_live_ em código de navegador, em app ou em repositório.| Limite | Valor |
|---|---|
| Requisições da API por conta | Padrão de 30 por minuto, compartilhado por todas as chaves da conta; o plano pode ter mais. Cada documento gasta uma chamada de download. Em 429, respeite o Retry-After. Veja Limites de requisição. |
| Validade da URL de um documento | 15 minutos, assinada, temporária. |
| Validade da URL do ZIP | 60 segundos e um único download. |
| Prazo de resposta do seu endpoint | 20 segundos por tentativa. |
| Tentativas por evento | 6, numa janela de cerca de 7 horas. Depois, FAILED, reenviável pela API. |
| Endpoints de webhook por conta | 20, ativos e inativos. |
| Desativação automática | O webhook com falhas seguidas é desativado após 3 dias e 20 entregas FAILED, com aviso por e-mail antes. Eventos disparados com o webhook desativado não são enviados depois. |
| O que o aviso traz | Ids e hashes. Nunca o arquivo, nem link de download, nem link de assinatura. |
| Visibilidade da chave | Só baixa o que o usuário dono da chave enxerga; o resto responde 404. |
| Origem do arquivo | A cópia no seu Drive é sua. O documento selado continua guardado na SuperSign, e esta integração não apaga nada de nenhum dos dois lados. |
FAILED com GET /v4/api/webhooks/{webhookId}/deliveries?status=FAILED e POST .../deliveries/{deliveryId}/retry.GET /v4/api/envelopes/?status=COMPLETED&updatedSince=<data ISO> lista os envelopes concluídos desde a última varredura, e GET /v4/api/envelopes/{envelopeId}/documents devolve os ids dos documentos. Baixe só o que ainda não está no Drive.