Criar Webhook

Registra uma nova URL para receber notificacoes de eventos via webhook.

Requisicao

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	Obrigatorio	Descricao
url	string	Sim	URL que recebera as notificacoes. Deve ser HTTPS.
events	string[]	Sim	Lista de eventos para escutar.
active	boolean	Nao	Se o webhook esta ativo. Default: true.

Eventos disponiveis

envelope.created, envelope.sent, envelope.completed,
envelope.canceled, envelope.expired, signer.notified,
signer.viewed, signer.signed, signer.declined,
document.uploaded

HTTPS obrigatorio

A URL do webhook deve utilizar HTTPS. URLs com HTTP serao rejeitadas pela API.

Exemplo de requisicao

curl -X POST https://api.tapsign.com.br/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com.br/webhooks/tapsign",
    "events": [
      "envelope.completed",
      "signer.signed",
      "signer.declined"
    ],
    "active": true
  }'

Resposta

Status: 201 Created

{
  "id": "wh_abc123def456",
  "url": "https://meusite.com.br/webhooks/tapsign",
  "events": [
    "envelope.completed",
    "signer.signed",
    "signer.declined"
  ],
  "active": true,
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "createdAt": "2026-03-29T14:30:00Z",
  "updatedAt": "2026-03-29T14:30:00Z"
}

Salve o secret imediatamente

O campo secret so e retornado uma unica vez, no momento da criacao do webhook. Ele e necessario para verificar a assinatura das notificacoes recebidas. Se voce perder o secret, sera necessario excluir o webhook e criar um novo.

Campos da resposta

Campo	Tipo	Descricao
id	string	Identificador unico do webhook
url	string	URL registrada
events	string[]	Eventos configurados
active	boolean	Status do webhook
secret	string	Chave para verificacao HMAC-SHA256. So aparece na criacao.
createdAt	string	Data de criacao (ISO 8601)
updatedAt	string	Data da ultima atualizacao (ISO 8601)

Erros comuns

Status	Codigo	Descricao
400	INVALID_URL	URL invalida ou nao utiliza HTTPS
400	INVALID_EVENTS	Lista de eventos vazia ou contem eventos invalidos
409	WEBHOOK_URL_EXISTS	Ja existe um webhook registrado para essa URL
401	UNAUTHORIZED	Token de autenticacao invalido ou ausente