Criar Webhook

Registra uma URL para receber os eventos de documento via webhook. Nesta página também estão as rotas para listar e atualizar webhooks.

Requisição

POST /v1/webhooks

URL completa: https://api.tapsign.com.br/v1/webhooks

Headers

Header	Valor
Authorization	Bearer {token}
Content-Type	application/json

Body

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome para identificar o webhook. Até 100 caracteres.
url	string	Sim	URL que receberá os POST. Até 2048 caracteres. Precisa ser HTTPS pública.
secret	string	Sim	Segredo usado para assinar cada entrega (HMAC-SHA256). Até 512 caracteres. Nunca é devolvido nas respostas.
events	string[]	Sim	De 1 a 20 eventos. Use ["*"] para receber todos.

Eventos aceitos

doc_viewed, doc_signed, doc_refused, doc_completed, doc_canceled, doc_expired, *

A descrição de cada um está em Eventos.

Confira a grafia dos eventos

A API não recusa nomes fora dessa lista. Um evento escrito errado (por exemplo envelope.completed) é salvo normalmente, mas nunca dispara.

Validação da URL

Em produção a URL precisa usar https:// e o host não pode resolver para endereço privado, loopback ou link-local (por exemplo localhost, 127.0.0.1, 10.0.0.5 ou 192.168.0.10). A validação acontece no cadastro, na atualização e de novo a cada envio. No ambiente de testes essas duas travas são relaxadas.

Exemplo de requisição

curl -X POST https://api.tapsign.com.br/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ERP produção",
    "url": "https://meusite.com.br/webhooks/tapsign",
    "secret": "um-segredo-longo-e-aleatorio",
    "events": ["doc_completed", "doc_refused", "doc_expired"]
  }'

Resposta

Status: 201 Created

{
  "id": 7,
  "name": "ERP produção",
  "url": "https://meusite.com.br/webhooks/tapsign",
  "hasSecret": true,
  "events": ["doc_completed", "doc_refused", "doc_expired"],
  "active": true,
  "createdAt": "2026-09-12T14:30:00Z",
  "updatedAt": "2026-09-12T14:30:00Z"
}

Guarde o segredo

O secret é definido por você e nunca volta nas respostas (hasSecret: true só indica que existe um). Guarde o mesmo valor no seu servidor para verificar a assinatura das entregas. Para trocar o segredo, envie um novo valor em Atualizar webhook.

Campos da resposta

Campo	Tipo	Descrição
id	integer	Identificador do webhook, usado para atualizar, excluir e consultar logs
name	string	Nome do webhook
url	string	URL registrada
hasSecret	boolean	Indica se há um segredo configurado
events	string[]	Eventos configurados
active	boolean	Se o webhook está recebendo entregas. Todo webhook nasce ativo
createdAt	string	Data de criação (ISO 8601, UTC)
updatedAt	string	Data da última atualização (ISO 8601, UTC)

---

Listar webhooks

Retorna todos os webhooks do usuário autenticado, ativos e inativos. A resposta é uma lista simples (sem paginação) com os mesmos campos acima.

GET /v1/webhooks

curl -X GET https://api.tapsign.com.br/v1/webhooks \
  -H "Authorization: Bearer {token}"

Status: 200 OK

[
  {
    "id": 7,
    "name": "ERP produção",
    "url": "https://meusite.com.br/webhooks/tapsign",
    "hasSecret": true,
    "events": ["doc_completed", "doc_refused", "doc_expired"],
    "active": true,
    "createdAt": "2026-09-12T14:30:00Z",
    "updatedAt": "2026-09-12T14:30:00Z"
  }
]

---

Atualizar webhook

Atualiza um webhook existente. Todos os campos são opcionais: envie apenas o que quer alterar.

PUT /v1/webhooks/{id}

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
id	integer	Sim	Identificador do webhook

Body

Campo	Tipo	Descrição
name	string	Novo nome. Até 100 caracteres
url	string	Nova URL. Até 2048 caracteres, com a mesma validação do cadastro
secret	string	Novo segredo. Até 512 caracteres. Omita para manter o atual
events	string[]	Nova lista de eventos (substitui a anterior). Até 20 itens
active	boolean	false pausa as entregas sem excluir o webhook; true reativa

Exemplo: pausar um webhook

curl -X PUT https://api.tapsign.com.br/v1/webhooks/7 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Status: 200 OK, com o webhook atualizado no mesmo formato da criação.

---

Erros comuns

Status	Quando acontece
400	Campo obrigatório ausente ou acima do tamanho permitido. O objeto fields indica qual campo falhou
400	URL sem HTTPS, sem host válido, com host que não resolve ou que aponta para rede privada. O motivo vem em details (por exemplo Webhook URL must use HTTPS)
401	Token ausente ou inválido, ou chave de API desativada
404	Na atualização: webhook inexistente ou de outro usuário

O formato completo das respostas de erro está em Status de Erros.