Webhooks de saída

Os webhooks de saída avisam o seu sistema, em tempo real, quando algo acontece com um envelope: o ODSign faz uma chamada POST com um JSON para o endereço que você cadastrar. Assim, o seu ERP ou CRM pode, por exemplo, baixar o contrato assim que todos assinarem, sem precisar consultar a API o tempo todo.

Nota: Disponível conforme o plano contratado, somente para administradores da conta. Veja Funcionalidades disponíveis na sua conta.

Onde encontrar

No menu lateral, abra Configurações › Webhooks. A página Webhooks de saída lista os webhooks da conta, cada um com seus eventos e as últimas entregas.

Eventos disponíveis

Reenvios manuais, lembretes e a expiração do envelope não geram eventos. Para saber se um envelope expirou, consulte o status pela API.

Passo a passo: criar um webhook

1. Em Configurações › Webhooks, clique em Novo webhook.
2. Em URL, informe o endereço público, http ou https, que vai receber as chamadas (até 255 caracteres). Prefira https.
3. Em Eventos, marque os eventos que interessam. O evento envelope.completed já vem marcado.
4. Clique em Salvar.
5. Copie o segredo que aparece no aviso Copie o segredo do webhook agora (ele começa com whsec_) e guarde-o no seu sistema. Ele serve para conferir a assinatura de cada entrega (veja Validar a assinatura dos webhooks).

Atenção: O segredo é exibido uma única vez. Se você o perder, exclua o webhook e crie outro, com um novo segredo.

O que o seu sistema recebe

Cada entrega é um POST com corpo JSON e estes cabeçalhos:

Exemplo de corpo do evento recipient.signed:

{
  "event": "recipient.signed",
  "sent_at": "2026-11-11T13:42:11+00:00",
  "envelope": {
    "id": "9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40",
    "subject": "Contrato de prestação de serviços",
    "status": "delivered",
    "sent_at": "2026-11-11T13:05:12+00:00",
    "completed_at": null,
    "final_sha256": null
  },
  "recipient": {
    "id": 2051,
    "name": "Maria Souza",
    "email": "maria@exemplo.com.br",
    "status": "signed",
    "routing_order": 1
  }
}

• sent_at (no topo) é a data e hora em que o evento foi gerado.
• Nos eventos envelope.*, recipient vem como null.
• Em envelope.completed, completed_at e final_sha256 vêm preenchidos. Use o id para baixar os arquivos com GET /envelopes/{id}/documents/final e GET /envelopes/{id}/documents/certificate.
• recipient.email pode vir null quando o destinatário recebeu o envelope apenas pelo celular.

Entregas e novas tentativas

• Uma entrega é bem-sucedida quando o seu endereço responde com um código 2xx. Responda rápido (em poucos segundos): o ODSign espera a resposta por um tempo limite definido pela plataforma.
• Se a resposta for outro código, ou não vier, o ODSign tenta de novo: são até 3 tentativas, a primeira na hora, a segunda cerca de 10 segundos depois e a última cerca de 1 minuto depois.
• Redirecionamentos (códigos 3xx) não são seguidos e contam como falha. Cadastre o endereço final.
• Endereços internos, como localhost e IPs privados, são recusados no cadastro e em cada entrega.

No cartão de cada webhook, a tabela mostra as 10 últimas entregas, com Quando, Evento, Situação (Entregue, Falhou ou Pendente), HTTP (o código que o seu servidor devolveu), Tentativas e Erro.

Dica: Como uma entrega pode chegar mais de uma vez (por exemplo, quando o seu servidor processou o evento mas demorou a responder), trate os eventos de forma idempotente: use o event, o envelope.id e o recipient.id para ignorar repetições.

Testar, editar, desligar e excluir

• Testar: envia na hora um evento test.ping para a URL e mostra o resultado, como "Teste entregue (HTTP 200)." ou "Falha no teste: ..." seguido do motivo. O teste funciona mesmo com o webhook desligado.
• Editar: muda a URL e os eventos. Na edição aparece a chave Ativo; desligue-a para pausar as entregas sem perder o cadastro (o cartão passa a mostrar Inativo).
• Excluir: remove o webhook. A mensagem "Webhook excluído." traz o botão Desfazer por alguns segundos.

Problemas comuns

• "A URL aponta para um endereço interno ou reservado." O endereço é localhost, um IP privado ou resolve para um deles. Use um endereço público. Para testes locais, use um serviço de túnel que forneça um endereço público.
• "Não foi possível localizar o servidor da URL." O nome do servidor não existe ou o DNS ainda não foi propagado.
• "Não inclua usuário e senha na URL." Tire as credenciais do endereço e confira a autenticidade das chamadas pela assinatura X-Signature.
• As entregas aparecem como Falhou com "HTTP 301" ou "HTTP 302". O endereço redireciona. Cadastre a URL final, geralmente com https.
• "Sem resposta do servidor (tempo limite de ... s ou falha de conexão)." O seu servidor demorou demais ou está fora do ar. Responda 2xx logo ao receber e faça o processamento pesado depois, em segundo plano.
• O menu Webhooks não aparece. Só administradores veem o item, e somente quando o plano inclui webhooks.