Events

Every event published in Factuarea is persisted as a read-only event object with an opaque id (a UUID v7, e.g. 01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d), consistent with the id of every other v1 resource. This lets you:

• Query it via API: GET /v1/events/{id} and GET /v1/events?type=invoice.paid.
• Deliver it to subscribed webhook endpoints (the same object is sent in the delivery body — see Webhooks).
• Replay a delivery from the dashboard (Developers > Webhooks > Deliveries).

Payload shape

Every event shares this structure:

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d",
  "object": "event",
  "type": "invoice.paid",
  "aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03",
  "api_version": "2026-05-22",
  "livemode": true,
  "data": {
    "invoice": { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03" }
  },
  "created": "2026-05-15T10:23:18Z"
}

Fields:

• id — opaque identifier of the event (UUID v7). Use it as the idempotency key on your side.
• object — always event.
• type — event name as <category>.<action> (e.g. invoice.paid, quote.approved).
• aggregate_id — UUID v7 of the resource that produced the event (e.g. the invoice for invoice.paid). null for events without a backfilled aggregate. Distinct from id, which identifies the event itself.
• api_version — date-based version the payload was serialized under, sealed at emission. Always present on events emitted today; null only for legacy events emitted before versions were sealed.
• livemode — true for events generated in production (live key, fact_live_); false for events generated in test mode (sandbox company, fact_test_ key). Test-mode events are recorded and queryable via GET /v1/events, but not delivered to webhook endpoints (see Test mode & sandbox), so any event your endpoint actually receives is always livemode: true.
• data — a thin reference to the affected resource, keyed by its type — e.g. { "invoice": { "id": "..." } }. Fetch the resource from its own endpoint to get the full, current representation.
• created — ISO 8601 UTC timestamp of when the event was created.

Idempotency

Each event has a unique id. Webhooks redeliver the same id to the same endpoint on every retry. In your handler:

event_id = event['id']
if seen_in_db(event_id):
    return '', 200
process(event)
mark_seen_in_db(event_id)

Event catalog

The full, authoritative catalog of subscribable event types is returned by GET /v1/event-catalog. Each entry carries a name, a category, a human-readable description, and a status (available or coming_soon):

curl https://api.factuarea.com/v1/event-catalog \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

{
  "data": [
    {
      "name": "invoice.paid",
      "category": "invoice",
      "description": "Factura pagada",
      "status": "available"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Representative event types by category (query the catalog for the complete, up-to-date list):

Invoices

invoice.created, invoice.updated, invoice.sent, invoice.paid, invoice.cancelled, invoice.annulled, invoice.overdue, invoice.deleted, invoice.number_assigned, invoice.rectified, invoice.email_sent, invoice.payment_reminder_sent, invoice.simplified_created, invoice.verifactu_submitted, invoice.metadata_changed.

Quotes

quote.created, quote.updated, quote.deleted, quote.approved, quote.rejected, quote.converted, quote.expired, quote.number_assigned, quote.metadata_changed.

Pro-forma invoices

proforma.created, proforma.updated, proforma.deleted, proforma.accepted, proforma.rejected, proforma.cancelled, proforma.expired, proforma.converted_to_invoice, proforma.number_assigned, proforma.metadata_changed.

Delivery notes

delivery_note.created, delivery_note.updated, delivery_note.status_changed, delivery_note.signed, delivery_note.converted.

Purchase invoices

purchase_invoice.created, purchase_invoice.updated, purchase_invoice.paid, purchase_invoice.payment_registered, purchase_invoice.cancelled, purchase_invoice.metadata_changed.

Recurring invoices

recurring_invoice.created, recurring_invoice.activated, recurring_invoice.paused, recurring_invoice.updated, recurring_invoice.deleted, recurring_invoice.completed, recurring_invoice.executed, recurring_invoice.failed, recurring_invoice.cancelled, recurring_invoice.metadata_changed.

Clients & products

client.created, client.updated, client.deleted, client.metadata_changed, product.created, product.updated.

Series & taxes

series.created, series.updated, series.deleted, series.archived, series.unarchived, series.marked_as_default, series.number_consumed, tax.metadata_changed, tax.validity_changed, payment.received.

FacturaE (FACe)

facturae.face_submitted, facturae.face_status_changed, facturae.face_cancellation_requested.

Payload examples

invoice.paid

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d",
  "object": "event",
  "type": "invoice.paid",
  "aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03",
  "api_version": "2026-05-22",
  "livemode": true,
  "data": {
    "invoice": { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03" }
  },
  "created": "2026-05-15T11:42:08Z"
}

client.updated

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a1a",
  "object": "event",
  "type": "client.updated",
  "aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a2b",
  "api_version": "2026-05-22",
  "livemode": true,
  "data": {
    "client": { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a2b" }
  },
  "created": "2026-05-15T11:50:12Z"
}

quote.converted

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a3c",
  "object": "event",
  "type": "quote.converted",
  "aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a4d",
  "api_version": "2026-05-22",
  "livemode": true,
  "data": {
    "quote": { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a4d" }
  },
  "created": "2026-05-15T12:01:55Z"
}

The event carries only a thin reference to the affected resource. Fetch the resource from its own endpoint (e.g. GET /v1/quotes/{id}) to read the converted invoice it links to.

Subscribe to events

Via API:

curl -X POST https://api.factuarea.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.mycompany.com/factuarea/webhook",
    "enabled_events": ["invoice.paid", "quote.approved"]
  }'

To subscribe to all events (not recommended in production except for internal dashboards):

{ "enabled_events": ["*"] }

To subscribe to entire families (all invoice.*):

{ "enabled_events": ["invoice.*", "quote.*"] }

List events via API

GET /v1/events?type=invoice.paid&limit=50

Available filters: type, type[in], created[gte], created[lte], created[gt], created[lt]. Standard cursor pagination (limit, starting_after, ending_before) — see Pagination.