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

# Lifecycle Events

> Feed transaction outcomes back to Specter to close the fraud feedback loop.

Fraud models and rules improve when they learn what happened **after** a decision. Lifecycle events report the
real outcome of a transaction — authorization, capture, chargeback, and more — back to Specter, which fans them
out to participating backends and uses them to auto-populate [blacklists](/products/specter/concepts/blacklist).

Submit an event with `POST /api/events`. Events are processed **synchronously**: the
response includes a `backend_notifications` entry for every backend call made before returning. Retrieve a
persisted event with `GET /api/events/{id}`.

## Event types

| Type            | Description                                                       |
| --------------- | ----------------------------------------------------------------- |
| `authorization` | Card authorization outcome (AVS/CVV results reveal data quality). |
| `capture`       | Payment captured.                                                 |
| `refund`        | Amount refunded.                                                  |
| `void`          | Authorization voided.                                             |
| `chargeback`    | Chargeback filed — the ground truth for fraud.                    |
| `fraud_report`  | An explicit fraud report.                                         |

Lifecycle event types must be a valid step in the payment's lifecycle (an authorization before a capture,
and so on); events that are not are rejected. `fraud_report` is the exception — see below.

## Fraud reports

Fraud is not a payment-lifecycle state: a transaction can turn out fraudulent whether it was captured,
merely authorized, or never reported to Specter beyond the original decision. A `fraud_report` event is
therefore accepted in **any** payment state — including for decisions that never received a lifecycle
event at all — and never changes `payment_state`.

Accepting a fraud report sets the decision's **fraud marker**, returned on the decision resource:

| Field             | Value                                                |
| ----------------- | ---------------------------------------------------- |
| `fraud_marked_at` | When the report was accepted.                        |
| `fraud_source`    | Copied from the event's `data.source`, when present. |
| `fraud_reason`    | Copied from the event's `data.reason`, when present. |

The marker is permanent and first-write-wins: repeat reports are accepted and kept in the event log, but
the marker keeps the values from the first report. Like every `fraud_report`, they also fan out to
backends and can auto-populate the blacklist.

```json theme={null}
{
  "type": "fraud_report",
  "decision_id": "dec_01J...",
  "occurred_at": "2026-07-28T12:00:00Z",
  "data": { "source": "issuer_report", "reason": "stolen card" }
}
```

## Request

An event references the originating `decision_id`; its `data` is a free-form map stored with the event and
forwarded to backends that support the event type.

```json theme={null}
{
  "type": "chargeback",
  "decision_id": "dec_01J...",
  "occurred_at": "2026-03-17T12:00:00Z",
  "data": { "amount": 1999, "reason": "4853" }
}
```

## Backend fan-out

Specter forwards each event to every backend that participated in the original decision and supports the event
type. Backends are reached through a [Link integration](/products/specter/concepts/backends).

A backend declares which event types it supports. When an event targets a type a backend does not support,
Specter records `status: "skipped"` — not an error. The `backend_notifications` array in the response reports
the outcome of every backend call.

## Blacklist auto-population

A [blacklist rule](/products/specter/concepts/blacklist) can listen for specific event types (`fraud_report`,
`chargeback`, `failed`) and automatically add the originating decision's field values to the blacklist — so a
card that produces a chargeback is blocked on its next attempt.

## Related

<CardGroup cols={2}>
  <Card title="Blacklist" icon="ban" href="/products/specter/concepts/blacklist">
    Auto-populate blocks from fraud and chargeback events.
  </Card>

  <Card title="Decisions" icon="check-double" href="/products/specter/concepts/decisions#resolving-a-review-decision">
    Resolve REVIEW decisions and notify backends.
  </Card>
</CardGroup>