Referência da APIEndpoints de webhook

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.

Escoposwebhooks:escrever

Linguagem dos exemplos
URL base
# Produçãohttps://api.emissordenota.com/v1# Sandboxhttps://sandbox.api.emissordenota.com/v1

Endpoints

  • GET/v1/webhooksLista os endpoints cadastrados
  • POST/v1/webhooksCadastra um endpoint
  • POST/v1/webhooks/{id}/testarEnvia um evento de teste
  • DELETE/v1/webhooks/{id}Remove um endpoint

O objeto endpoint

idstring
Identificador do endpoint, com o prefixo wh_.
urlstring
Endereço HTTPS que recebe os eventos.
eventosarray
Os eventos que o endpoint assina.
segredostring
Usado para conferir a assinatura das entregas. Aparece completo só na resposta do cadastro.
ativoboolean
Vem false quando o endpoint está pausado e não recebe entregas.
criado_emstring
Data e hora do cadastro, em ISO 8601.
O objeto endpoint
{  "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

urlstringobrigatório
Precisa usar HTTPS e responder em até 10 segundos.
eventosarrayobrigatório
Um ou mais eventos da lista do guia de Webhooks.
descricaostringopcional
Texto livre para identificar o endpoint no painel.
POST /v1/webhooks
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

eventostringopcional
O evento a simular. O padrão é nfse.autorizada.
POST /v1/webhooks/{id}/testar · 200 OK
{  "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

StatusCódigoQuando

  • 404webhook_nao_encontrado
    O id não existe nesse ambiente.
  • 422url_invalida
    A URL não usa HTTPS.
  • 422evento_desconhecido
    Há um evento fora da lista.