Integration event inbox

A payment gateway sends Factuarea an event for everything that happens on your account: a charge succeeded, a refund was issued, a subscription cycle was billed, a payout landed. Most of those events produce something — an invoice, a corrective invoice, a payment record. Some produce nothing, and when that happens the interesting question is always the same: why didn't this charge become an invoice?

The integration event inbox answers it. Every event Factuarea receives is recorded with what it produced and, when it produced nothing, a typed discard reason drawn from a closed catalogue. No guessing from logs, no support ticket: the reason is a value you can filter on, and for the reasons you can act upon it comes with the next step and, sometimes, with the ability to reprocess the event.

The inbox is gateway-agnostic. It records events from every integration that writes history — including gateways that are not released yet and historical events of one that gets retired — because hiding those rows would leave you without an explanation for charges that never got invoiced.

Three endpoints expose it:

The same surface exists as MCP tools — list_integrations_events, get_integrations_event and replay_integrations_event — with the same scopes.

Browsing the inbox

Newest first, scoped to the authenticated company. Cursor-based pagination with limit (1 to 100, defaults to 25) and starting_after:

curl -G https://api.factuarea.com/v1/integrations/events \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "provider=stripe" \
  --data-urlencode "status=skipped" \
  --data-urlencode "limit=50"

{
  "data": [
    {
      "id": "0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f",
      "object": "integration_event",
      "provider": "stripe",
      "event_type": "invoice.paid",
      "direction": "inbound",
      "status": "skipped",
      "discard_reason": "subscription_autoinvoicing_disabled",
      "discard_reason_label": "Auto-facturación de suscripciones desactivada",
      "is_actionable": true,
      "is_replayable": true,
      "error_message": null,
      "duration_ms": 412,
      "created_at": "2026-07-14T09:31:07Z"
    }
  ],
  "has_more": true,
  "next_cursor": "84120"
}

Treat next_cursor as opaque: for this listing it is a numeric string, not a UUID v7 like the cursors of the document listings. Feed it back verbatim in starting_after.

discard_reason_label is returned in Spanish, the language of the product's own interface. If you build a panel in another language, key your own copy on discard_reason — that value is the stable, closed identifier.

Filters

discard_reason is the closed axis; event_type is not an enum. The event_type column deliberately mixes two conventions: branches instrumented later store the raw provider type (charge.refunded), while pre-existing ones keep their own semantic value (autoinvoice.*). Match it exactly when you know what you are after, but never model it as a closed set — you would be modelling something the column does not guarantee.

is_parked=false is not the same as omitting the parameter. The first one excludes parked events; the second one excludes nothing.

A value outside its catalogue returns 422, and an unknown query parameter returns 400 parameter_unknown instead of being silently ignored — a filter that gets dropped in silence hands you a page you believe is narrowed when it is not.

The catalogue of discard reasons

Twenty typed reasons, one per discard branch of the gateway webhook pipeline. Each one declares two business decisions that are not decorative flags:

• Actionable — can the account owner do something about it? Only actionable reasons notify. Telling someone about a discard they cannot resolve teaches them to ignore the inbox, and that is how the notification that mattered gets missed.
• Parked — could reprocessing the same content produce a different outcome? Only parked events keep their content encrypted and accept a replay.

The rule behind the parked column: an event is parked when the discard was caused by an external state you can change (a toggle that is off, a connected account that came unlinked, a currency with no exchange rate yet). It is not parked when the cause is the content of the event itself (malformed, duplicate, uncovered type, zero amount, cycle already invoiced) — reprocessing it would take exactly the same branch and only write a second row. Hence the invariant: every parked reason is actionable, and six of the nine actionable ones are parked.

A reason with nothing to do says so explicitly. Eleven of the twenty are informational, and the contract does not invent an instruction for them: the detail endpoint returns recommended_action: null rather than a sentence manufactured to fill the field.

Notifications: only what you can fix

An actionable discard notifies the account's administrators. An informational one never does.

The notification is throttled: if an unread notice already exists for the same company, gateway and reason within the last 24 hours, no second one is created — a misconfigured webhook fires hundreds of identical events. The condition is unread on purpose: once you have read it and discards keep arriving, the next one does notify. That is not noise, it means the incident is still live.

Parking and the 30-day window

When a reason is parkable, Factuarea stores the raw event encrypted at rest, so that it can be reprocessed later. That content is never returned by the API — not in the listing, not in the detail. It holds personal data of your end customers and payment details, and it exists for exactly one purpose: making the replay possible.

The content is purged 30 days after the event was parked. The row survives: its reason, its status, its date and its is_parked flag stay in your inbox indefinitely, because the record that a charge did not produce an invoice is history you may need long after the content expired.

The detail: what to do next

The detail endpoint returns everything the listing does, plus recommended_action: one imperative sentence with the next step for that specific reason, or null when the reason is informational.

curl https://api.factuarea.com/v1/integrations/events/0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

The sentence deliberately tells reproducible reasons ("… and replay the event") apart from the ones that are not ("… issue it by hand"), so it never points you at an operation that would answer 422.

An event of another company and an event that does not exist return the same 404 resource_not_found. The endpoint never reveals whether an id exists elsewhere.

Replaying a parked event

Reprocess a gateway event that was parked, once the cause that prevented it from producing its effect is gone — you turned automatic invoicing back on, you re-linked the connected account, the official exchange rate of the day became available.

curl -X POST https://api.factuarea.com/v1/integrations/events/0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f/replay \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Four properties of this operation matter more than its signature:

• It does not duplicate invoices. The replay goes through the very same idempotency check as the original attempt, so if that charge already produced an invoice, the job stops on its own and creates nothing.
• It is asynchronous. 202 means accepted and queued, not completed. The body returns the event as it stands now — its is_replayable is still true — not the outcome of the retry. The outcome shows up as a new event in the inbox, so poll GET /v1/integrations/events to see how it ended.
• If the cause is still present, the event is discarded again and recorded once more. That is correct, and it is observable.
• It takes no input. Any query parameter or body key returns 400 parameter_unknown instead of being ignored. Sending one means you believe you are configuring something about the retry — a mode, a series, a date — that this operation does not support, and silently accepting it would confirm that false expectation about an action that can issue an invoice. An empty body or no body at all is the normal case.

When a replay is refused

is_replayable: true is the contract: when it is true, the replay does not answer 422. It is the conjunction of three conditions — the event is parked, it still holds its content, and its reason admits reprocessing — evaluated in that same order by the very handler that guards the replay. That is what lets you offer a retry button without guessing.

The three refusals all return 422 business_rule_violation and tell you which one it is through the subcode:

Where this fits

• Stripe auto-invoicing — the flow that produces most of the events you will find here, including the subscription cycles whose toggle is behind subscription_autoinvoicing_disabled.
• Payouts and bank reconciliation — the payout ingestion behind payout_missing_id and payout_connected_account_missing.
• Test mode — validate your handling of the inbox with a fact_test_ key before you wire a replay button to a production credential.
• Error codes — the envelope of the 400, 404 and 422 responses quoted above.