---
title: "Referência: Endpoints de webhook"
description: "Referência dos endpoints de webhook da API: objeto endpoint, cadastrar com segredo de assinatura, enviar um evento de teste, remover e erros possíveis."
url: https://docs.emissordenota.com/referencia/webhooks
language: pt-BR
---
# Endpoints de webhook

Os endereços do seu sistema que recebem os eventos. Cada endpoint tem a própria lista de eventos e o próprio segredo de assinatura.

**Escopos**: webhooks:escrever

**URL base**

```bash
# Produção
https://api.emissordenota.com/v1

# Sandbox
https://sandbox.api.emissordenota.com/v1
```

## Endpoints

- `GET /v1/webhooks`: Lista os endpoints cadastrados
- `POST /v1/webhooks`: Cadastra um endpoint
- `POST /v1/webhooks/{id}/testar`: Envia um evento de teste
- `DELETE /v1/webhooks/{id}`: Remove um endpoint

## O objeto endpoint

- `id` (string): Identificador do endpoint, com o prefixo wh_.
- `url` (string): Endereço HTTPS que recebe os eventos.
- `eventos` (array): Os eventos que o endpoint assina.
- `segredo` (string): Usado para conferir a assinatura das entregas. Aparece completo só na resposta do cadastro.
- `ativo` (boolean): Vem false quando o endpoint está pausado e não recebe entregas.
- `criado_em` (string): Data e hora do cadastro, em ISO 8601.

**O objeto endpoint**

```json
{
  "id": "wh_5Rk8sNc2Yd",
  "url": "https://seusistema.com.br/webhooks/emissor",
  "eventos": [
    "nfse.autorizada",
    "nfse.rejeitada",
    "guia.disponivel"
  ],
  "segredo": "whsec_Tz4Lm9Qx2Vb7Kc1Nw8Ry5Pd3",
  "ativo": true,
  "criado_em": "2026-11-03T11:27:40-03:00"
}
```

## Cadastrar um endpoint

`POST /v1/webhooks`

Cria o endpoint e devolve o segredo de assinatura. Guarde o segredo na hora: ele não aparece completo de novo.

**Corpo da requisição**

- `url` (string, obrigatório): Precisa usar HTTPS e responder em até 10 segundos.
- `eventos` (array, obrigatório): Um ou mais eventos da lista do guia de Webhooks.
- `descricao` (string, opcional): Texto livre para identificar o endpoint no painel.

**POST /v1/webhooks**

```bash
curl -X POST https://api.emissordenota.com/v1/webhooks \
  -H "Authorization: Bearer $EDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusistema.com.br/webhooks/emissor",
    "eventos": ["nfse.autorizada", "nfse.rejeitada"]
  }'
```

## Enviar um evento de teste

`POST /v1/webhooks/{id}/testar`

Dispara uma entrega com dados de exemplo, assinada com o segredo do endpoint. A resposta traz o status devolvido pelo seu servidor.

**Corpo da requisição**

- `evento` (string, opcional): O evento a simular. O padrão é nfse.autorizada.

**POST /v1/webhooks/{id}/testar · 200 OK**

```json
{
  "evento_id": "evt_2Vn6cXp9Lt",
  "evento": "nfse.autorizada",
  "status_http": 200,
  "duracao_ms": 184
}
```

## Remover um endpoint

`DELETE /v1/webhooks/{id}`

Remove o endpoint e responde 204, sem corpo. As entregas pendentes para ele são descartadas.

## Erros

| Status | Código | Quando |
| --- | --- | --- |
| 404 | webhook_nao_encontrado | O id não existe nesse ambiente. |
| 422 | url_invalida | A URL não usa HTTPS. |
| 422 | evento_desconhecido | Há um evento fora da lista. |
