Webhooks

Permissions: webhooks.view for fetches; webhooks.manage for registration, deletion, test and retry.

GET/v1/webhooks200 OK

full_accessinvoices_read_write

Lists the webhook configurations of the account.

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

Response — 200 OK

{
  "data": [
    {
      "id": "7b8c9d0e-1f2a-4b3c-8d5e-6f7a8b9c0d1e",
      "url": "https://integracao.example.com/webhooks/corvo",
      "events": [
        "nfse.invoice.authorized"
      ],
      "active": true,
      "createdAt": "2026-10-10T12:00:00.000Z",
      "updatedAt": "2026-10-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

The listing never returns secret.

POST/v1/webhooks201 Created

full_access

Registers a webhook configuration.

Field	Type	Required	Description
url	string	✓	Must use HTTP or HTTPS and must not point to private/loopback/link-local hosts.
events	string[]	✓	Non-empty array containing only accepted public events (list below).

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"
    ]
  }'

Response — 201 Created

{
  "data": {
    "id": "7b8c9d0e-1f2a-4b3c-8d5e-6f7a8b9c0d1e",
    "url": "https://integracao.example.com/webhooks/corvo",
    "events": [
      "nfse.invoice.authorized"
    ],
    "active": true,
    "secret": "whsec_...",
    "createdAt": "2026-10-10T12:00:00.000Z",
    "updatedAt": "2026-10-10T12:00:00.000Z"
  }
}

Store the secret at creation time — it never comes back in the listing. active starts as true.

Subscribed events

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 is used by the test route and cannot be included in the subscription array. Accepting an event at registration does not guarantee that every failure path of the current processing emits it; do not rely solely on failed/reconciliation_required without fetching the invoice.

DELETE/v1/webhooks/:id200 OK

full_access

Deletes a webhook configuration.

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

Response — 200 OK

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

Returns 404 if the configuration is not present in the account.

POST/v1/webhooks/:id/test200 OK

full_access

Sends a webhook.test event — always with environment test — to the registered URL.

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

Response — 200 OK

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

{ "sent": true } is returned when your endpoint answers 2xx. Otherwise the response is still 200 with { "sent": false, "statusCode": 405, "error": "..." } (statusCode is null if the endpoint could not be reached). A failed test attempt does not schedule the normal retries.

GET/v1/webhooks/deliveries200 OK

full_accessinvoices_read_write

Lists webhook deliveries, newest first.

Field	Type	Description
hours	number	Window in hours (default `24`); it stays fixed on following pages.
limit	integer	Defaults to `50`; accepts integers from 1 to 1000 (an invalid value returns `400`).
cursor	string	`nextCursor` from the previous page, keeping the same filters.
environment	string	`test` or `live`.

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

Response — 200 OK

{
  "data": [
    {
      "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "webhookConfigId": "7b8c9d0e-1f2a-4b3c-8d5e-6f7a8b9c0d1e",
      "eventType": "nfse.invoice.authorized",
      "environment": "test",
      "url": "https://integracao.example.com/webhooks/corvo",
      "statusCode": 200,
      "status": "sent",
      "durationMs": 120,
      "retryCount": 0,
      "createdAt": "2026-10-10T12:00:05.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "eyJ2IjoxLCJjcmVhdGVkQXQiOiIyMDI2LTEwLTA5VDEyOjAwOjAwLjAwMDAwMFoiLCJpZCI6IjNmMWM4YTkwIn0"
  }
}

Fields include id, webhookConfigId, eventType, environment, url, payload?, statusCode?, responseBody?, errorMessage?, status, durationMs?, retryCount, nextRetryAt?, lastError?, createdAt. Delivery status values: pending, sent, delayed, failed, manual_retry. Without ?environment, the listing may return both environments of the account.

GET/v1/webhooks/deliveries/stats200 OK

full_accessinvoices_read_write

Fetches delivery statistics for the recent window.

Field	Type	Required	Description
hours	number		Defaults to `24`.
environment	string		`test` or `live`.

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

Response — 200 OK

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

The current implementation computes over up to 1000 recent deliveries. manual_retry counts toward total but has no counter of its own; the sum of the four counters can be smaller than total.

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

full_access

Schedules a new delivery attempt for a failed delivery.

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

Response — 200 OK

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

Schedules the delivery with status: manual_retry and resets its counter — it does not mean the receiver already got the event. Returns 404 for a delivery missing from the account.