Webhooks

Cadastre endpoints e acompanhe as entregas de eventos.

Permissões: webhooks.view para consultas; webhooks.manage para cadastro, exclusão, teste e retry.

GET/v1/webhooks200 OK

full_accessinvoices_read_write

Lista as configurações de webhook da conta.

curl "$BASE_URL/webhooks" -H "X-API-Key: $CORVO_API_KEY"

Resposta — 200 OK

{
  "data": [
    {
      "id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "url": "https://integracao.example.com/webhooks/corvo",
      "events": [
        "nfse.invoice.authorized",
        "nfse.invoice.documents_ready"
      ],
      "active": true,
      "createdAt": "2026-10-10T12:00:00.000Z",
      "updatedAt": "2026-10-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

A listagem não devolve secret.

POST/v1/webhooks201 Created

full_access

Cadastra uma configuração de webhook.

Campo	Tipo	Obrigatório	Descrição
url	string	✓	Deve incluir protocolo HTTP ou HTTPS e não apontar para hosts privados/loopback/link-local.
events	string[]	✓	Array não vazio contendo somente eventos públicos aceitos (lista abaixo).

curl -X POST "$BASE_URL/webhooks" \
  -H "X-API-Key: $CORVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://integracao.example.com/webhooks/corvo",
    "events": [
      "nfse.invoice.authorized",
      "nfse.invoice.documents_ready",
      "nfse.invoice.email_sent",
      "nfse.invoice.email_failed"
    ]
  }'

Resposta — 201 Created

{
  "data": {
    "id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "url": "https://integracao.example.com/webhooks/corvo",
    "events": [
      "nfse.invoice.authorized",
      "nfse.invoice.documents_ready",
      "nfse.invoice.email_sent",
      "nfse.invoice.email_failed"
    ],
    "active": true,
    "createdAt": "2026-10-10T12:00:00.000Z",
    "updatedAt": "2026-10-10T12:00:00.000Z",
    "secret": "segredo-exibido-apenas-na-criacao"
  }
}

Guarde o secret no momento do cadastro; ele não volta na listagem. active inicia como true.

Eventos aceitos

nfse.invoice.authorized
nfse.invoice.rejected
nfse.invoice.failed
nfse.invoice.reconciliation_required
nfse.invoice.manual_review
nfse.invoice.documents_ready
nfse.invoice.email_sent
nfse.invoice.email_failed
nfse.invoice.fiscal_discrepancy
nfse.invoice.cancelled
nfse.invoice.cancellation_rejected

webhook.test é usado pela rota de teste e não pode ser incluído no array de inscrições. A aceitação de um evento no cadastro não garante que todos os caminhos de falha do processamento atual o emitam; não dependa exclusivamente de failed/reconciliation_required sem consultar a nota.

DELETE/v1/webhooks/:id200 OK

full_access

Exclui uma configuração de webhook.

curl -X DELETE "$BASE_URL/webhooks/$WEBHOOK_ID" \
  -H "X-API-Key: $CORVO_API_KEY"

Resposta — 200 OK

{
  "data": {
    "deleted": true
  }
}

Retorna 404 se a configuração estiver ausente na conta.

POST/v1/webhooks/:id/test200 OK

full_access

Envia o evento webhook.test para a URL cadastrada.

curl -X POST "$BASE_URL/webhooks/$WEBHOOK_ID/test" \
  -H "X-API-Key: $CORVO_API_KEY"

Resposta — 200 OK

{
  "data": {
    "sent": true
  }
}

O evento é enviado sempre com ambiente test. Retorna { "sent": true } quando seu endpoint responde 2xx. Caso contrário a resposta continua 200, com { "sent": false, "statusCode": 405, "error": "..." } (statusCode é null se o endpoint não foi alcançado). A tentativa de teste não agenda os retries normais em caso de falha.

GET/v1/webhooks/deliveries200 OK

full_accessinvoices_read_write

Lista as entregas de webhook, ordenadas por criação decrescente.

Query

Campo	Tipo	Descrição
hours	number	Janela em horas (padrão `24`); fica fixa nas páginas seguintes.
limit	integer	Padrão `50`; aceita inteiros de 1 a 1000 (valor inválido retorna `400`).
cursor	string	`nextCursor` da página anterior, mantendo os mesmos filtros.
environment	string	`test` ou `live`.

curl "$BASE_URL/webhooks/deliveries?hours=24&limit=50" \
  -H "X-API-Key: $CORVO_API_KEY"

Resposta — 200 OK

{
  "data": [
    {
      "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
      "eventType": "nfse.invoice.authorized",
      "environment": "test",
      "url": "https://integracao.example.com/webhooks/corvo",
      "statusCode": 200,
      "status": "sent",
      "retryCount": 0,
      "createdAt": "2026-10-10T12:02:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "eyJ2IjoxLCJjcmVhdGVkQXQiOiIyMDI2LTEwLTA5VDEyOjAwOjAwLjAwMDAwMFoiLCJpZCI6IjNmMWM4YTkwIn0"
  }
}

Campos: id, webhookConfigId, eventType, environment, url, payload?, statusCode?, responseBody?, errorMessage?, status, durationMs?, retryCount, nextRetryAt?, lastError?, createdAt. Status de entrega: pending, sent, delayed, failed, manual_retry. Sem o filtro ?environment, a listagem pode retornar ambos os ambientes da conta.

GET/v1/webhooks/deliveries/stats200 OK

full_accessinvoices_read_write

Consulta estatísticas das entregas recentes.

Query

Campo	Tipo	Obrigatório	Descrição
hours	integer		Padrão `24`.
environment	string		`test` ou `live`.

curl "$BASE_URL/webhooks/deliveries/stats?hours=24" \
  -H "X-API-Key: $CORVO_API_KEY"

Resposta — 200 OK

{
  "data": {
    "total": 10,
    "sent": 7,
    "failed": 1,
    "pending": 1,
    "delayed": 1
  }
}

A implementação atual calcula sobre até 1000 entregas recentes. manual_retry entra no total, mas não tem contador próprio: a soma dos quatro contadores pode ser menor que total.

POST/v1/webhooks/deliveries/:id/retry200 OK

full_access

Agenda nova tentativa de entrega de um webhook.

curl -X POST "$BASE_URL/webhooks/deliveries/$DELIVERY_ID/retry" \
  -H "X-API-Key: $CORVO_API_KEY"

Resposta — 200 OK

{
  "data": {
    "retried": true
  }
}

Agenda a entrega com status: manual_retry e reinicia seu contador — não significa que o receptor já recebeu o evento. 404 para entrega ausente na conta.