> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook event reference

> Complete reference for every Tilta webhook event type – buyer, facility, order, and invoice – organized by resource with payload fields and JSON examples.

Every event Tilta emits follows the `RESOURCE.PROCESS.OUTCOME` dot-notation convention. This page lists every available event type grouped by resource, describes the fields present in each event's `data` payload, and provides JSON examples for key events. You can subscribe to individual leaf events or to any prefix to receive all descendant events – see [Webhooks](/docs/webhooks) for subscription mechanics.

***

## Buyer events

Buyer events fire when a buyer record is created or updated on your platform. These events are useful for keeping your own data store in sync with Tilta's buyer registry.

| Event type      | When it fires                                 |
| --------------- | --------------------------------------------- |
| `BUYER.CREATED` | A new buyer has been successfully created     |
| `BUYER.UPDATED` | An existing buyer has been replaced via `PUT` |

### Payload fields

Both `BUYER.CREATED` and `BUYER.UPDATED` share the same `data` shape:

| Field         | Type   | Description                               |
| ------------- | ------ | ----------------------------------------- |
| `external_id` | string | Your platform's identifier for this buyer |
| `legal_name`  | string | The buyer's registered legal entity name  |

### Examples

<Tabs>
  <Tab title="BUYER.CREATED">
    ```json theme={null}
    {
      "id": "3f8a2c10-11e4-4b2a-9f0d-1a2b3c4d5e6f",
      "occurred_at": 1701862836,
      "type": "BUYER.CREATED",
      "data": {
        "external_id": "buyer-acme-001",
        "legal_name": "Acme GmbH"
      }
    }
    ```
  </Tab>

  <Tab title="BUYER.UPDATED">
    ```json theme={null}
    {
      "id": "7c3e1a09-88f2-4d5b-b1c0-2e3f4a5b6c7d",
      "occurred_at": 1701870000,
      "type": "BUYER.UPDATED",
      "data": {
        "external_id": "buyer-acme-001",
        "legal_name": "Acme Europe GmbH"
      }
    }
    ```
  </Tab>
</Tabs>

***

## Facility events

Credit Facility events cover the full lifecycle of a buyer's credit line – from initial creation through renewal, limit increases, expiry, and freeze states. All facility events include `buyer_external_id` in their `data` payload so you can associate the event with the correct buyer in your system.

### Creation

Emitted when a buyer applies for a credit facility and Tilta processes the underwriting decision.

| Event type                    | When it fires                                        |
| ----------------------------- | ---------------------------------------------------- |
| `FACILITY.CREATION.IN_REVIEW` | Application submitted and pending manual review      |
| `FACILITY.CREATION.ACCEPTED`  | Credit facility approved; buyer can now place orders |
| `FACILITY.CREATION.REJECTED`  | Application declined                                 |

| Field               | Type                     | Present on       |
| ------------------- | ------------------------ | ---------------- |
| `buyer_external_id` | string                   | All three events |
| `expires_at`        | integer (Unix timestamp) | `ACCEPTED` only  |

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "occurred_at": 1701862836,
  "type": "FACILITY.CREATION.ACCEPTED",
  "data": {
    "buyer_external_id": "buyer-acme-001",
    "expires_at": 1709638836
  }
}
```

### Renewal

Credit Facilities are renewed every 3 months. Renewal events mirror the Creation trio and fire when an automatic or triggered renewal is processed.

| Event type                   | When it fires                                          |
| ---------------------------- | ------------------------------------------------------ |
| `FACILITY.RENEWAL.IN_REVIEW` | Renewal submitted and pending review                   |
| `FACILITY.RENEWAL.ACCEPTED`  | Facility renewed; new expiry date set                  |
| `FACILITY.RENEWAL.REJECTED`  | Renewal declined; buyer can no longer place new orders |

| Field               | Type                     | Present on                                     |
| ------------------- | ------------------------ | ---------------------------------------------- |
| `buyer_external_id` | string                   | All three events                               |
| `expires_at`        | integer (Unix timestamp) | `ACCEPTED` only – contains the new expiry date |

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "occurred_at": 1709638900,
  "type": "FACILITY.RENEWAL.ACCEPTED",
  "data": {
    "buyer_external_id": "buyer-acme-001",
    "expires_at": 1717414900
  }
}
```

### Limit increase

Emitted when a credit limit increase is requested on an existing facility.

| Event type                    | When it fires                                       |
| ----------------------------- | --------------------------------------------------- |
| `FACILITY.INCREASE.IN_REVIEW` | Limit increase request submitted and pending review |
| `FACILITY.INCREASE.ACCEPTED`  | Limit increase approved                             |
| `FACILITY.INCREASE.REJECTED`  | Limit increase declined                             |

| Field               | Type    | Present on                                                |
| ------------------- | ------- | --------------------------------------------------------- |
| `buyer_external_id` | string  | All three events                                          |
| `amount`            | integer | `ACCEPTED` only – approved increase amount in minor units |
| `currency`          | string  | `ACCEPTED` only – ISO 4217 currency code (e.g., `EUR`)    |

```json theme={null}
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "occurred_at": 1710000000,
  "type": "FACILITY.INCREASE.ACCEPTED",
  "data": {
    "buyer_external_id": "buyer-acme-001",
    "amount": 5000000,
    "currency": "EUR"
  }
}
```

### Status events

These events reflect changes to a facility's operational state rather than an underwriting process.

| Event type          | When it fires                                            |
| ------------------- | -------------------------------------------------------- |
| `FACILITY.EXPIRED`  | Facility reached its expiry date and was not renewed     |
| `FACILITY.FROZEN`   | Facility frozen due to late or unpaid invoices           |
| `FACILITY.UNFROZEN` | Facility restored after outstanding amounts were settled |

All three carry only `buyer_external_id` in their `data` payload.

```json theme={null}
{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "occurred_at": 1712000000,
  "type": "FACILITY.FROZEN",
  "data": {
    "buyer_external_id": "buyer-acme-001"
  }
}
```

<Note>
  When you receive `FACILITY.FROZEN`, the buyer can no longer have new orders authorized against their facility. Update your checkout flow to block payment terms for this buyer until you receive `FACILITY.UNFROZEN`.
</Note>

***

## Order events

Order events track the lifecycle of a purchase intent from confirmation through disbursement. All order events include `external_id` (your platform's order identifier) and `status` in their `data` payload.

| Event type        | `status` Value | When it fires                                                       |
| ----------------- | -------------- | ------------------------------------------------------------------- |
| `ORDER.CONFIRMED` | `CONFIRMED`    | Order successfully authorized against the buyer's facility          |
| `ORDER.CANCELLED` | `CANCELLED`    | Order cancelled before an invoice was created                       |
| `ORDER.EXPIRED`   | `EXPIRED`      | Order authorization window elapsed without an invoice being created |
| `ORDER.CLOSED`    | `CLOSED`       | All associated invoices are settled and the order is complete       |
| `ORDER.DISBURSED` | `DISBURSED`    | Merchant payout for the order has been initiated                    |

### Payload fields

| Field         | Type   | Description                                   |
| ------------- | ------ | --------------------------------------------- |
| `external_id` | string | Your platform's identifier for this order     |
| `status`      | string | The new status of the order (see table above) |

### Example

```json theme={null}
{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "occurred_at": 1712100000,
  "type": "ORDER.CONFIRMED",
  "data": {
    "external_id": "order-789",
    "status": "CONFIRMED"
  }
}
```

<Tip>
  Subscribe to `ORDER.EXPIRED` to detect when an authorized order was not converted to an invoice within the allowed window. Use this event to prompt your platform to re-authorize or cancel the order on your side.
</Tip>

***

## Invoice events

Invoice events cover the full invoice lifecycle: creation, due date, closure, financing payout, and document management. Invoices are the legally effective financing step – they trigger merchant payouts and start the buyer's repayment clock.

### Lifecycle events

| Event type        | When it fires                                            |
| ----------------- | -------------------------------------------------------- |
| `INVOICE.CREATED` | Invoice successfully created and financing initiated     |
| `INVOICE.DUE`     | Invoice has reached its due date and payment is expected |
| `INVOICE.CLOSED`  | Invoice fully settled by the buyer                       |

| Field               | Type   | Present on                                             |
| ------------------- | ------ | ------------------------------------------------------ |
| `external_id`       | string | All three events                                       |
| `buyer_external_id` | string | `INVOICE.CREATED` only                                 |
| `status`            | string | `INVOICE.DUE` (`"DUE"`), `INVOICE.CLOSED` (`"CLOSED"`) |

<Tabs>
  <Tab title="INVOICE.CREATED">
    ```json theme={null}
    {
      "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
      "occurred_at": 1712200000,
      "type": "INVOICE.CREATED",
      "data": {
        "external_id": "inv-2024-001",
        "buyer_external_id": "buyer-acme-001"
      }
    }
    ```
  </Tab>

  <Tab title="INVOICE.DUE">
    ```json theme={null}
    {
      "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
      "occurred_at": 1714800000,
      "type": "INVOICE.DUE",
      "data": {
        "external_id": "inv-2024-001",
        "status": "DUE"
      }
    }
    ```
  </Tab>

  <Tab title="INVOICE.CLOSED">
    ```json theme={null}
    {
      "id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
      "occurred_at": 1715000000,
      "type": "INVOICE.CLOSED",
      "data": {
        "external_id": "inv-2024-001",
        "status": "CLOSED"
      }
    }
    ```
  </Tab>
</Tabs>

### Financing event

| Event type                   | When it fires                                              |
| ---------------------------- | ---------------------------------------------------------- |
| `INVOICE.FINANCING.PAID_OUT` | Tilta has disbursed funds to the merchant for this invoice |

| Field               | Type   | Description                                |
| ------------------- | ------ | ------------------------------------------ |
| `external_id`       | string | Your platform's identifier for the invoice |
| `buyer_external_id` | string | Your platform's identifier for the buyer   |

```json theme={null}
{
  "id": "c9d0e1f2-a3b4-5678-cdef-789012345678",
  "occurred_at": 1712300000,
  "type": "INVOICE.FINANCING.PAID_OUT",
  "data": {
    "external_id": "inv-2024-001",
    "buyer_external_id": "buyer-acme-001"
  }
}
```

### File events

File events fire when documents attached to an invoice (such as PDFs) are created, deleted, or replaced. These are useful for keeping your document management system in sync with Tilta's records.

| Event type              | When it fires                                         |
| ----------------------- | ----------------------------------------------------- |
| `INVOICE.FILE.CREATED`  | A file has been attached to an invoice                |
| `INVOICE.FILE.DELETED`  | An attached file has been removed                     |
| `INVOICE.FILE.REPLACED` | An existing file has been replaced with a new version |

| Field                | Type   | Present on                                                           |
| -------------------- | ------ | -------------------------------------------------------------------- |
| `file_name`          | string | All three events – name of the new or affected file                  |
| `file_type`          | string | All three events – MIME type or document category                    |
| `replaced_file_name` | string | `INVOICE.FILE.REPLACED` only – name of the file that was overwritten |

```json theme={null}
{
  "id": "d0e1f2a3-b4c5-6789-defa-890123456789",
  "occurred_at": 1712400000,
  "type": "INVOICE.FILE.REPLACED",
  "data": {
    "file_name": "invoice-2024-001-v2.pdf",
    "file_type": "application/pdf",
    "replaced_file_name": "invoice-2024-001-v1.pdf"
  }
}
```

***

## Subscription quick reference

Use this table to decide what to subscribe to based on your integration needs:

| Use case                                   | Recommended subscription     |
| ------------------------------------------ | ---------------------------- |
| React when a buyer's facility is approved  | `FACILITY.CREATION.ACCEPTED` |
| Handle all facility underwriting decisions | `FACILITY.CREATION`          |
| Monitor all facility lifecycle changes     | `FACILITY`                   |
| Unlock checkout after order authorization  | `ORDER.CONFIRMED`            |
| Detect abandoned orders                    | `ORDER.EXPIRED`              |
| Confirm merchant payout                    | `INVOICE.FINANCING.PAID_OUT` |
| Track all invoice activity                 | `INVOICE`                    |
| Sync all buyer changes                     | `BUYER`                      |