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:

Cadastre o endpoint na Sandbox, como em Webhooks → Cadastrar um endpoint, e guarde o signingSecret.

Crie e envie um envelope de teste: chega ENVELOPE_SENT.

Assine pelo link recebido: chegam SIGNATORY_SIGNED e, ao final, ENVELOPE_COMPLETED.

Para ver ENVELOPE_VOIDED, anule um envelope de teste.

Se preferir não criar um envelope, use o evento de teste.

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.

Enviar evento de teste

Para confirmar que o seu endpoint recebe e valida a assinatura sem criar um envelope, peça um evento de teste. A SuperSign® envia na hora um único POST ao endpoint, pelo mesmo caminho dos eventos reais (mesma checagem de URL, mesmo segredo de assinatura, mesmo cabeçalho X-SuperSign-Signature), e devolve na resposta o que o seu servidor respondeu:

A resposta é 200, mesmo quando o seu servidor falha. O que aconteceu está nos campos:

{
  "deliveryId": "5f0c2c7e-0000-4000-8000-000000000001",
  "status": "DELIVERED",
  "httpStatus": 200,
  "durationMs": 184,
  "errorType": null,
  "responseSnippet": "ok"
}

Campo	Descrição
`deliveryId`	Id da entrega de teste. Ela aparece em `GET /v4/api/webhooks/{webhookId}/deliveries` com `event` `WEBHOOK_TEST`.
`status`	`DELIVERED` (seu servidor respondeu `2xx`), `FAILED` (erro de rede, DNS, TLS, tempo esgotado, redirect, `3xx`, `4xx`, `5xx` ou URL recusada) ou `SKIPPED` (conta suspensa ou sem API no plano; nada foi enviado).
`httpStatus`	Status HTTP que o seu servidor devolveu, ou `null` quando não houve resposta.
`durationMs`	Duração da tentativa, em milissegundos.
`errorType`	Classificação da falha (`timeout`, `dns`, `tls`, `conexao`, `http_status`, `redirect`, `url_insegura`...). `null` quando `DELIVERED`. A lista pode crescer: trate valor desconhecido como falha.
`responseSnippet`	Até 500 caracteres do corpo da resposta, com dados pessoais mascarados. Nunca traz cabeçalhos.

O corpo enviado ao seu endpoint tem o mesmo formato externo dos outros eventos, sem envelope, participante nem dado pessoal:

{
  "id": "9d3f6a52-0000-4000-8000-000000000002",
  "event": "WEBHOOK_TEST",
  "createdAt": "2026-10-07T14:00:02.000Z",
  "data": {
    "accountId": "c1b2a3d4-0000-4000-8000-000000000003",
    "test": true
  }
}

Na Sandbox o corpo também traz "environment": "sandbox" e o cabeçalho X-SuperSign-Environment: sandbox, como nos demais eventos. O id muda a cada teste.

Regras do teste:

Uma tentativa, 10 segundos. Não há retentativa: o resultado é o da única tentativa. O tempo máximo de espera é de 10 segundos (nos eventos reais, 20).

Não conta para a desativação automática. O teste não soma falha seguida nem zera uma contagem em andamento, e um teste que falha nunca desativa o endpoint. Veja Desativação automática.

Funciona com o endpoint desativado. Assim você valida a URL antes de reativar com PATCH. O teste não reativa o endpoint.

Limite de 10 testes por minuto por endpoint. Acima disso a resposta é 429 RATE_LIMIT_EXCEEDED com Retry-After.

Mesma proteção de URL dos eventos reais. URL que resolve para rede privada ou serviço de metadados não recebe nada: a resposta é 200 com status FAILED e errorType url_insegura.

Escopo webhooks:write. O teste dispara um POST ao seu servidor. Chave de outra conta, ou webhook que não é da sua conta, recebe 404 RESOURCE_NOT_FOUND.

Não exige Idempotency-Key e nunca devolve resultado antigo: cada chamada envia de novo.

Não é reenviável. Para repetir, chame o teste outra vez. O retry de uma entrega de teste responde 409 WEBHOOK_DELIVERY_NOT_RESENDABLE.

Não é um evento assinável. WEBHOOK_TEST não entra no campo events do cadastro; é recebido por todo endpoint que pedir o teste.

O endpoint precisa ter segredo de assinatura para o cabeçalho X-SuperSign-Signature ser enviado, como em qualquer evento. Endpoint antigo sem segredo recebe o teste sem assinatura; gire o segredo para habilitá-la (veja Girar o segredo de assinatura).

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:

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.

Guarde e confirme. Valide o evento e registre-o ou enfileire-o duravelmente, com unicidade e inserção atômica pelo id. Responda 2xx somente após essa aceitação durável; em falha de gravação, responda um status retentável. Se a ferramenta não garantir esse comportamento, use um receptor intermediário que o implemente, sem presumir que responder imediatamente no nó garante persistência (veja Confirmação durável e Resposta e retentativas).

Filtre e processe. Use um nó IF no campo event para o trabalho assíncrono. Ignore duplicatas já registradas e marque o processamento como concluído somente após sucesso, permitindo retentativa após falha.

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.

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).