> For the complete documentation index, see [llms.txt](https://chekin.gitbook.io/chekin-public-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chekin.gitbook.io/chekin-public-api/api-reference/einvoicing/webhooks/invoice-webhooks.md).

# Invoice webhooks

Invoice issuance is asynchronous, so instead of polling [List Invoices](/chekin-public-api/api-reference/einvoicing/invoices/list-invoices.md) you can configure webhooks on the supplier to be notified when an invoice is created, successfully legalized, or fails.

### 1. Configure `webhook_configurations` when creating or updating a supplier

When [creating](/chekin-public-api/api-reference/einvoicing/suppliers/create-new-supplier.md) or [updating](/chekin-public-api/api-reference/einvoicing/suppliers/update-supplier.md) a supplier, set the `webhook_configurations` field:

```json
{
  "webhook_configurations": [
    {
      "event": "CREATED",
      "url": "https://a39a98db-b867-44ab-b7a5-e5909f3c8fc9.webhook.site",
      "authorization": null
    },
    {
      "event": "COMPLETED",
      "url": "https://a39a98db-b867-44ab-b7a5-e5909f3c8fc9.webhook.site",
      "authorization": null
    },
    {
      "event": "FAILED",
      "url": "https://a39a98db-b867-44ab-b7a5-e5909f3c8fc9.webhook.site",
      "authorization": null
    }
  ]
}
```

| Parameter       | Type           | Description                                                                                                                                                                                                                                   |
| --------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event`         | enum           | Event that triggers the webhook: `CREATED`, `COMPLETED`, `FAILED` (see below)                                                                                                                                                                 |
| `url`           | string         | URL the webhook is sent to                                                                                                                                                                                                                    |
| `authorization` | object \| null | (Optional) Authorization config for requests sent to your server. See [Create new Supplier](/chekin-public-api/api-reference/einvoicing/suppliers/create-new-supplier.md#webhook_configurations-field-optional-all-providers) for the schema. |

* `CREATED` — the invoice has been created and sent to the tax system, and is currently being processed.
* `COMPLETED` — the invoice has been successfully legalized and the invoice PDF file has been received.
* `FAILED` — an error occurred while processing the invoice, for example an issue with the guest data.

{% hint style="info" %}
Configure all three events to track an invoice through its full lifecycle.
{% endhint %}

### 2. `CREATED` webhook

Once an invoice is issued, you receive a webhook like the following:

```json
{
    "invoice": {
        "id": "9d6426aea2ac11f19712820154af1ecc",
        "created_at": "2026-08-28T06:49:28.385759",
        "updated_at": "2026-08-28T06:49:29.384611",
        "deleted_at": null,
        "tag": "INV-1MBW-000002",
        "total_amount": "10.40",
        "status": "NEW",
        "reservation_id": "c35f8b8054d640d7a344f58970fe1c74",
        "supplier_id": "e69825cd-47c1-4446-9559-96c0a8b9dc99",
        "supplier_name": "Test supplier ",
        "housing_id": "0c0929cb-8e94-496d-99a4-d47db1999b35",
        "provider": "ADE",
        "file_url": null,
        "status_details": null,
        "type": "STANDARD",
        "action": null,
        "data": null,
        "error_details": {}
    },
    "event": "CREATED",
    "message": "Invoice created successfully",
    "timestamp": "2026-08-28T06:49:29.478340+00:00"
}
```

Here `event` is `CREATED` and the invoice itself has the `NEW` status: the invoice was created successfully and is currently being processed by the tax authority.

### 3. `COMPLETED` webhook

Once the invoice has been processed successfully, you receive the following webhook:

```json
{
    "invoice": {
        "id": "9d6426aea2ac11f19712820154af1ecc",
        "created_at": "2026-08-28T06:49:28.385759",
        "updated_at": "2026-08-28T06:49:42.811035",
        "deleted_at": null,
        "tag": "INV-1MBW-000002",
        "total_amount": "10.40",
        "status": "COMPLETED",
        "reservation_id": "c35f8b8054d640d7a344f58970fe1c74",
        "supplier_id": "e69825cd-47c1-4446-9559-96c0a8b9dc99",
        "supplier_name": "Test supplier ",
        "housing_id": "0c0929cb-8e94-496d-99a4-d47db1999b35",
        "provider": "ADE",
        "file_url": "https://api-ng.chekintest.xyz/api/v3/documents-v2/invoicing/invoices/9d6426ae-a2ac-11f1-9712-820154af1ecc/file",
        "status_details": null,
        "type": "STANDARD",
        "action": null,
        "data": null,
        "error_details": {}
    },
    "event": "COMPLETED",
    "message": "Invoice completed successfully",
    "timestamp": "2026-08-28T06:49:42.888403+00:00"
}
```

Here `event` is `COMPLETED`: the invoice was successfully legalized and the PDF file was received. The PDF can be downloaded from `invoice.file_url`.

### 4. `FAILED` webhook

If an error occurs while processing the invoice, you receive a `FAILED` webhook:

```json
{
    "invoice": {
        "id": "9d6426aea2ac11f19712820154af1ecc",
        "created_at": "2026-08-28T06:49:28.385759",
        "updated_at": "2026-08-28T06:49:42.811035",
        "deleted_at": null,
        "tag": "INV-1MBW-000002",
        "total_amount": "10.40",
        "status": "ERROR",
        "reservation_id": "c35f8b8054d640d7a344f58970fe1c74",
        "supplier_id": "e69825cd-47c1-4446-9559-96c0a8b9dc99",
        "supplier_name": "Test supplier ",
        "housing_id": "0c0929cb-8e94-496d-99a4-d47db1999b35",
        "provider": "ADE",
        "file_url": null,
        "status_details": "Invoice processing failed: Invalid fiscal code for customer: test_fiscal_code",
        "type": "STANDARD",
        "action": null,
        "data": null,
        "error_details": {}
    },
    "event": "FAILED",
    "message": "Invoice processing failed",
    "timestamp": "2026-08-28T06:49:42.888403+00:00"
}
```

Here, `invoice.status_details` contains a message explaining what went wrong.

{% hint style="warning" %}

* If several invoices are issued at the same time, a separate webhook is sent for each invoice.
* Webhooks are only sent after the invoice has been created successfully. If invoice creation fails immediately and you receive an error in the initial API response, do not expect a `FAILED` webhook for that invoice.
  {% endhint %}