SuperSign - API Oficial
  1. Introdução
  • SuperSign API Pública
    • Introdução
      • Primeiro envelope em 5 minutos
      • Integrar com IA
      • Testar a API no Postman
      • Paginação e filtros
      • Catálogo de erros
      • Receitas em Node.js, PHP e Python
      • Changelog
      • Idempotência e erros
      • Estados do envelope
      • Webhooks
      • Limites de requisição
      • Criar um envelope a partir de um modelo
      • Gerar um cliente (SDK)
      • Webhooks — Evento ENVELOPE_SENT
      • Webhooks — Evento SIGNATORY_SIGNED
      • Webhooks — Evento ENVELOPE_COMPLETED
      • Webhooks — Evento ENVELOPE_VOIDED
      • Webhooks — Evento ENVELOPE_EXPIRED
      • Webhooks — Segurança e verificação
      • Webhooks — Entregas, retentativas e reenvio
      • Webhooks — Testar na Sandbox e automatizar
    • Referência da API
      • Conta
        • Consultar a conta da integração
        • Consultar capacidades da integração
        • Consultar o catálogo de capacidades
        • Listar chamadas da própria chave
        • Consultar consumo do ciclo
        • Validar a chave de API
      • Envelopes
        • Excluir rascunho de envelope
        • Consultar histórico do envelope
        • Criar e enviar envelope numa chamada
        • Gerar URL de download do envelope em ZIP
        • Duplicar envelope
        • Criar rascunho de envelope
        • Listar envelopes
        • Atualizar configurações do envelope
        • Enviar envelope
        • Consultar envelope
        • Mover envelope para outra pasta
        • Anular envelope
      • Participantes
        • Listar participantes do envelope
        • Aprovar participante aprovador
        • Recusar como participante aprovador
        • Corrigir contato do participante
        • Sincronizar participantes
        • Enviar lembrete ao participante
      • Documentos
        • Listar documentos do envelope
        • Substituir campos do documento
        • Listar campos do documento
        • Confirmar o PDF convertido de um DOCX
        • Validar um documento selado
        • Reordenar documentos do envelope
        • Adicionar documento ao envelope
        • Gerar URL de download do documento
      • Contatos
        • Atualizar contato parcialmente
        • Listar envelopes do contato
        • Listar listas de contatos
        • Consultar lista de contatos
        • Criar contato
        • Listar contatos
        • Consultar contato
        • Atualizar contato
        • Excluir contato
      • Equipe
        • Listar grupos da conta
        • Listar membros da conta
      • Pastas
        • Listar conteúdo da pasta
        • Consultar acesso da pasta
        • Excluir pasta
        • Renomear pasta
        • Mover pasta
        • Listar todas as pastas
        • Criar pasta
      • Convites
        • Listar convites da conta
      • Webhooks
        • Excluir webhook
        • Listar entregas de um webhook
        • Detalhar uma entrega de webhook
        • Reenviar uma entrega de webhook
        • Girar o segredo de assinatura do webhook
        • Criar webhook
        • Listar webhooks
        • Atualizar webhook
      • Modelos
        • Listar modelos
        • Consultar modelo
        • Criar envelope a partir de modelo
        • Criar modelo em rascunho
        • Editar título e descrição do modelo
        • Consultar processamento do documento do modelo
        • Ativar modelo
        • Duplicar modelo
        • Enviar documentos do modelo
        • Definir vagas do modelo
        • Posicionar campos no documento do modelo
        • Apagar modelo em rascunho
        • Reordenar documentos do modelo
        • Remover documento do modelo
        • Definir cópias do modelo
      • Auditoria e relatórios
        • Listar envelopes anulados
        • Relatório de envelopes
        • Relatório de uso por grupo
      • Etiquetas
        • Aplicar etiqueta ao envelope
        • Remover etiqueta do envelope
        • Listar etiquetas da conta
  1. Introdução

Webhooks — Testar na Sandbox e automatizar

Como testar o recebimento antes de ir para produção e como trocar uma consulta em laço por webhook. Visão geral em Webhooks.

Testar na Sandbox#

Use a Sandbox (https://api.sandbox.supersign.com.br) com uma chave de teste
para desenvolver o receptor:
1.
Cadastre o endpoint na Sandbox, como em Webhooks → Cadastrar um endpoint, e guarde o signingSecret.
2.
Crie e envie um envelope de teste: chega ENVELOPE_SENT.
3.
Assine pelo link recebido: chegam SIGNATORY_SIGNED e, ao final, ENVELOPE_COMPLETED.
4.
Para ver ENVELOPE_VOIDED, anule um envelope de teste.
5.
Consulte as entregas com GET /v4/api/webhooks/{webhookId}/deliveries para ver o que foi enviado e o que seu endpoint respondeu.
Na Sandbox, o payload traz "environment": "sandbox" e a entrega leva o
header X-SuperSign-Environment: sandbox. Em Produção o campo e o header
são omitidos: o payload de produção continua exatamente como sempre foi,
para não quebrar receptor com validação estrita de schema.

Trocar a consulta em laço por webhook (n8n e similares)#

Consultar o mesmo envelope a cada poucos minutos para saber se ele terminou gasta o limite de requisições da conta e ainda chega atrasado. O webhook avisa no momento do evento. O fluxo abaixo usa n8n, mas vale para qualquer ferramenta de automação:
1.
Receba o evento. Crie um nó Webhook com método POST e cadastre a URL de produção dele como endpoint (veja Cadastrar um endpoint), assinando só os eventos de que o fluxo precisa — por exemplo, ENVELOPE_COMPLETED e ENVELOPE_VOIDED.
2.
Responda logo. Configure o nó para responder 200 imediatamente e deixe o resto do fluxo continuar depois. Um receptor lento vira falha de entrega e retentativa (veja Resposta e retentativas).
3.
Filtre e deduplique. Use um nó IF no campo event e guarde o id do evento para ignorar uma entrega repetida.
4.
Confirme pela API antes de agir. Com o data.envelope.id do evento, chame GET /v4/api/envelopes/{envelopeId} num nó HTTP Request com a chave no cabeçalho Authorization: Bearer .... Siga só se o estado for o esperado. Isso também protege o fluxo de uma chamada forjada para a URL do webhook.
5.
Desligue o laço antigo quando o novo fluxo estiver entregando.
Se a sua ferramenta dá acesso ao corpo cru da requisição, verifique também o cabeçalho X-SuperSign-Signature como descrito em Verificação da assinatura (HMAC).
Modificado em 2026-10-01 21:38:00
Página anterior
Webhooks — Entregas, retentativas e reenvio
Próxima página
Consultar a conta da integração
Built with