Webhook event reference

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 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

BUYER.CREATED
BUYER.UPDATED

{
  "id": "3f8a2c10-11e4-4b2a-9f0d-1a2b3c4d5e6f",
  "occurred_at": 1701862836,
  "type": "BUYER.CREATED",
  "data": {
    "external_id": "buyer-acme-001",
    "legal_name": "Acme GmbH"
  }
}

{
  "id": "7c3e1a09-88f2-4d5b-b1c0-2e3f4a5b6c7d",
  "occurred_at": 1701870000,
  "type": "BUYER.UPDATED",
  "data": {
    "external_id": "buyer-acme-001",
    "legal_name": "Acme Europe GmbH"
  }
}

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

{
  "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

{
  "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`)

{
  "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.

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

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.

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

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

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.

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"`)

INVOICE.CREATED
INVOICE.DUE
INVOICE.CLOSED

{
  "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "occurred_at": 1712200000,
  "type": "INVOICE.CREATED",
  "data": {
    "external_id": "inv-2024-001",
    "buyer_external_id": "buyer-acme-001"
  }
}

{
  "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
  "occurred_at": 1714800000,
  "type": "INVOICE.DUE",
  "data": {
    "external_id": "inv-2024-001",
    "status": "DUE"
  }
}

{
  "id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
  "occurred_at": 1715000000,
  "type": "INVOICE.CLOSED",
  "data": {
    "external_id": "inv-2024-001",
    "status": "CLOSED"
  }
}

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

{
  "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

{
  "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`

Get Started

Integration

Onboarding

Orders & Payments

Notifications & Communication

Platform & Reference

Webhook event reference

Buyer events

Payload fields

Examples

Facility events

Creation

Renewal

Limit increase

Status events

Order events

Payload fields

Example

Invoice events

Lifecycle events

Financing event

File events

Subscription quick reference

​Buyer events

​Payload fields

​Examples

​Facility events

​Creation

​Renewal

​Limit increase

​Status events

​Order events

​Payload fields

​Example

​Invoice events

​Lifecycle events

​Financing event

​File events

​Subscription quick reference

Buyer events

Payload fields

Examples

Facility events

Creation

Renewal

Limit increase

Status events

Order events

Payload fields

Example

Invoice events

Lifecycle events

Financing event

File events

Subscription quick reference