Receiving webhooks

Corvo sends a JSON POST to your registered URL. Respond with HTTP 2xx within 10 seconds; enqueue slow work in your receiver.

Request format

• Method: POST.
• Headers: Content-Type: application/json, X-Corvo-Signature: sha256=<hex>.
• Body: a JSON envelope with id, type, environment, createdAt and data.

{
  "id": "evt_identifier",
  "type": "nfse.invoice.authorized",
  "environment": "test",
  "createdAt": "2026-10-10T14:00:00.000Z",
  "data": {
    "invoiceId": "INVOICE_UUID",
    "companyId": "COMPANY_UUID",
    "environment": "test",
    "status": "authorized",
    "documentsStatus": "pending",
    "emailStatus": null,
    "stage": "authorized",
    "accessKey": "ACCESS_KEY",
    "nfseNumber": 123
  }
}

data varies by event; in the fiscal flow it includes the invoice's identification and state. Authorization adds accessKey/nfseNumber, rejection adds errorCode/errorMessage, manual review adds reason, ready documents add accessKey/nfseNumber/documentsReadyAt, and a sent email adds sentAt. The test event carries { "message": "This is a test webhook event" }.

Event types

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. webhook.test cannot be subscribed.

Signature verification

The signature is the HMAC-SHA256 of the sent JSON body with the configuration's secret, in hex. Verify the raw received body bytes — do not parse and stringify before verifying.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody, signatureHeader, secret) {
  if (typeof signatureHeader !== "string") return false;
  const match = /^sha256=([a-f0-9]{64})$/.exec(signatureHeader);
  if (!match) return false;
  const received = Buffer.from(match[1], "hex");
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  return timingSafeEqual(received, expected);
}

Always compare in constant time (timingSafeEqual) and verify against the raw body bytes.

Retries and delivery semantics

• The outbox makes up to 5 attempts, with intervals after a failure of 60 seconds, 160 seconds, 15 minutes and 30 minutes; execution depends on the worker.
• Retries preserve the original payload — deduplicate by the event id.
• The receiver may get the same event again; the current signature has no separate verification timestamp, so deduplication on the receiver is required.
• Do not assume a global delivery order.

Respond 2xx quickly and process asynchronously: the 10-second window applies to the HTTP response, not to the work itself.