---
title: "Registrar webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Registrar webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.signdocs.com.br`
- URL: `https://api.signdocs.com.br/v1/webhooks`
- Auth: HTTP bearer

Registra um novo endpoint de webhook para receber notificações de eventos.
O `secret` retornado na resposta é exibido apenas neste momento — armazene-o
com segurança para validar as assinaturas HMAC-SHA256 dos payloads recebidos.

Uma URL que já tem um webhook `ACTIVE` no tenant é recusada com `409`, qualquer
que seja a lista de eventos; o `webhookId` existente vem no `detail`. Para mudar
os eventos, remova o registro (`DELETE /v1/webhooks/{webhookId}`) e registre a
URL de novo — o novo registro recebe um novo `secret`.

Requer scope `webhooks:write`.

## Request body

- RegisterWebhookRequest: Requisição de registro de webhook.
  - `url` string, uri, required: URL do endpoint que receberá as notificações (HTTPS obrigatório).
  - `events` WebhookEventType[], required: Lista de tipos de evento para os quais o webhook será acionado.

## Response `201`

Webhook registrado com sucesso. O `secret` é retornado apenas nesta resposta.

- RegisterWebhookResponse: Resposta de registro de webhook. O campo `secret` é retornado **apenas nesta resposta** — armazene-o com segurança para validar assinaturas HMAC-SHA256.
  - `webhookId` string, required
  - `url` string, uri, required
  - `secret` string, required: Segredo HMAC-SHA256 para validação de payloads. Exibido apenas na criação.
  - `events` WebhookEventType[], required
  - `status` 'ACTIVE', required
  - `createdAt` string, date-time, required

## Other responses

- `400`: Requisição inválida — parâmetros ausentes ou malformados.
- `401`: Autenticação ausente ou inválida.
- `403`: Permissões insuficientes para a operação solicitada. Inclui `purpose: "ACTION_AUTHENTICATION"` sem `featureFlags.trustSessionsEnabled`. A verificação é pelo `purpose`, não pela rota: vale em `/v1/transactions`, `/v1/signing-sessions` e `/v1/envelopes/{envelopeId}/sessions`, além de `/v1/trust-sessions`. O remédio é habilitar a flag para o tenant e provisionar a cota `monthlyTrustSessions`.
- `409`: Conflito de estado — a operação não pode ser realizada no estado atual do recurso.
- `422`: Entidade não processável — a requisição é sintaticamente válida mas semanticamente incorreta. Inclui o perfil de política não autorizado para o tenant. As rotas de criação (`/v1/transactions`, `/v1/signing-sessions` e `/v1/envelopes/{envelopeId}/sessions`) verificam a mesma regra, antes de cota, convite e gravação — a recusa não consome documento. As flags envolvidas são `featureFlags.customPolicyEnabled` (perfil `CUSTOM`), `serpro.enabled` (perfis SERPRO), `featureFlags.documentExtractionEnabled` (fallback por documento; `BIOMETRIC_SERPRO_AUTO_FALLBACK` exige as duas últimas) e `featureFlags.biometricRequired`. O remédio é habilitar a flag para o tenant. `signer.cpf` e `signer.birthDate`, exigidos pelos perfis SERPRO, são validados como **400** e não aqui: requisição malformada, corrigível na mesma chamada.
- `500`: Erro interno do servidor.

---

[API](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api.md) · [All operations](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/revisions/2d3805aed161?raw)