Event catalog

Every webhook delivery carries a product event describing an invoice lifecycle milestone. All events share one envelope shape and wrap the invoice as it looked at that milestone, so a single handler can process any event type by switching on type. Events are delivered through configured webhook endpoints; there is no public endpoint to list or replay them.

The event envelope

An event has a stable envelope with the invoice nested under data.object. The nested object is the same Invoice shape returned by the developer API, reflecting the invoice's status at the moment the event was created.

  • idstring

    Public event ID, prefixed evt_. De-duplicate deliveries by this value.

  • objectevent

    Object type.

  • typestring

    Event type, one of the six invoice lifecycle events below.

  • modetest | live

    Whether the invoice is a test or live invoice.

  • account_idstring

    Public account ID.

  • organization_idstring

    Public organization ID.

  • created_atstring

    Event creation time. Events from one transaction can share a timestamp, and no global ordering is guaranteed.

  • dataobject

    Wrapper whose object field is the invoice at this milestone.

invoice.received

Emitted when a submission has been accepted into the product lifecycle. The nested invoice has status received. This is the earliest lifecycle event and confirms the invoice exists and is queued for processing.

invoice.processing

Emitted while the invoice is being processed or is waiting for due-time processing. The nested invoice has status processing. An invoice can pass through this state more than once when retries are involved.

invoice.accepted

Emitted when the invoice is accepted. The nested invoice has status accepted, and for accepted invoices ksef_number is populated; upo_available may still be false until a UPO artifact exists.

invoice.accepted
{  "id": "evt_V3sGDb5VXxLxzGzvYVw0Pw",  "object": "event",  "type": "invoice.accepted",  "mode": "test",  "account_id": "acct_Eu81D5X8m1py2TXdWR5fNg",  "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",  "created_at": "2026-05-31T10:18:30Z",  "data": {    "object": {      "id": "inv_2kCYq4m4G7YbUjvH0kC1dg",      "object": "invoice",      "mode": "test",      "status": "accepted",      "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",      "external_id": "fv-2026-0001",      "created_at": "2026-05-31T10:15:30Z",      "updated_at": "2026-05-31T10:18:30Z",      "ksef_number": "KSEF-TEST-8D7C6B5A4E3F2A1B0C9D",      "upo_available": true,      "retrying": false,      "next_retry_at": null,      "last_error": null,      "metadata": {        "order_id": "ord_123"      }    }  }}

invoice.rejected

Emitted for a non-retryable product or business rejection. The nested invoice has status rejected and carries a last_error describing the rejection.

invoice.rejected
{  "id": "evt_U8wYyy6fj34N1D6lH6ZPLQ",  "object": "event",  "type": "invoice.rejected",  "mode": "test",  "account_id": "acct_Eu81D5X8m1py2TXdWR5fNg",  "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",  "created_at": "2026-05-31T10:18:30Z",  "data": {    "object": {      "id": "inv_2kCYq4m4G7YbUjvH0kC1dg",      "object": "invoice",      "mode": "test",      "status": "rejected",      "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",      "external_id": "fv-2026-0001",      "created_at": "2026-05-31T10:15:30Z",      "updated_at": "2026-05-31T10:18:30Z",      "ksef_number": null,      "upo_available": false,      "retrying": false,      "next_retry_at": null,      "last_error": {        "code": "sandbox_invoice_rejected",        "message": "The sandbox invoice was rejected.",        "retryable": false      },      "metadata": {        "order_id": "ord_123"      }    }  }}

invoice.failed

Emitted for a technical or retry-exhausted processing failure. The nested invoice has status failed and carries a last_error with the failure code. Unlike a rejection, a failure indicates the invoice could not be processed rather than a business rule decision.

invoice.upo_available

Emitted when a persisted UPO XML artifact becomes available for an accepted invoice. The nested invoice has upo_available: true. After this event, the UPO can be retrieved through the developer API see Invoice lifecycle and UPO.

invoice.upo_available
{  "id": "evt_XjW1g8KMqJj6fW3Az7bXzQ",  "object": "event",  "type": "invoice.upo_available",  "mode": "test",  "account_id": "acct_Eu81D5X8m1py2TXdWR5fNg",  "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",  "created_at": "2026-05-31T10:18:30Z",  "data": {    "object": {      "id": "inv_2kCYq4m4G7YbUjvH0kC1dg",      "object": "invoice",      "mode": "test",      "status": "accepted",      "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",      "external_id": "fv-2026-0001",      "created_at": "2026-05-31T10:15:30Z",      "updated_at": "2026-05-31T10:18:30Z",      "ksef_number": "KSEF-TEST-8D7C6B5A4E3F2A1B0C9D",      "upo_available": true,      "retrying": false,      "next_retry_at": null,      "last_error": null,      "metadata": {        "order_id": "ord_123"      }    }  }}

The invoice.received, invoice.processing, and invoice.failed events use the same envelope, with data.object carrying the invoice at the corresponding status. See Invoice statuses for the full status list.