Events & the API envelope

The response envelope

Every /v1 response (except the bare health probes) is wrapped in a consistent envelope.

Success:

{
  "success": true,
  "data": { "...": "the actual result" },
  "meta": { "requestId": "req_aBcDeFgHiJkL" }
}

Error:

{
  "success": false,
  "error": { "code": "not_found", "message": "..." },
  "meta": { "requestId": "req_aBcDeFgHiJkL" }
}

• Read your result from data. Every schema in the API Reference describes the data payload.
• meta.requestId (req_…) identifies the request in Trile’s logs. Log it on your side and quote it in support requests.
• You may send your own x-request-id; Trile will echo it through as the request ID.

The event log

Trile records an immutable, append-only event (evt_…) for everything that happens to your account — subscriptions created, invoices paid, payments failed, and so on. It’s your source of truth for reconciliation and for replaying state you might have missed.

List and filter events:

curl "$TRILE_API/v1/events?type=invoice.paid&limit=50" \
  -H "x-api-key: $TRILE_KEY"

Filters include type, resourceType, resourceId, and date ranges. Paging is the standard cursor form.

Events vs. webhooks

	Event log (/v1/events)	Webhooks
Direction	You pull	Trile pushes
Guarantee	Always queryable, never expires	Delivered with retries; you verify signatures
Use it for	Reconciliation, backfill, audits, recovering from missed webhooks	Real-time reactions to billing events

A robust integration uses both: webhooks for low-latency reactions, and a periodic sweep of the event log to catch anything a webhook delivery missed.

Common event types

• subscription.created, subscription.updated, subscription.canceled
• invoice.created, invoice.paid, invoice.payment_failed
• customer.created, customer.updated

The authoritative, current list is what your account actually emits — query /v1/events in test mode to see real examples for your integration.