# Merchant webhook events (https://docs.chargeflow.io/docs/merchants/webhook-events)



Chargeflow emits webhook events so your system reacts to disputes and alerts in real time. Subscribe to the events your integration needs and Chargeflow delivers an HTTP POST to your endpoint whenever one fires. Formal payload schemas are generated from the spec and live in the [API reference](https://docs.chargeflow.io/docs/api/2025-04-01/merchants/webhooks-events); this page is the narrative catalog - when each event fires and what to do with it.

## Available events [#available-events]

| Event                                                     | Fires when                                        | What to do                                       |
| --------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ |
| [`dispute.created`](#dispute-created)                     | A new dispute is ingested and first-pass enriched | Trigger your enrichment flow                     |
| [`alerts.created`](#alerts-created)                       | A new pre-chargeback alert arrives                | Refund / mitigate (or trigger workflows)         |
| [`alerts.updated`](#alerts-updated)                       | An alert's outcome changes                        | Sync your records to the new outcome             |
| [`alerts.transaction.linked`](#alerts-transaction-linked) | An alert is matched to a PSP transaction          | Get the transaction to refund (merchant-managed) |

To register an endpoint and build a handler, see [Subscribe to webhook events](https://docs.chargeflow.io/docs/merchants/automation/subscribe-to-events). For signature verification and delivery/retry behavior, see [Webhooks](https://docs.chargeflow.io/docs/reference/concepts/webhooks).

<Callout title="Payload shapes differ by event">
  `dispute.created` arrives wrapped in an envelope (`{type, data, creationDate, webhookId}`) carrying the current dispute resource under `data`. The three alert events are delivered **flat, with no envelope** - their `type` field holds the alert type, not the event name.
</Callout>

<Callout title="Disputes are creation-only today">
  `dispute.created` is the only dispute event. Status changes, evidence submission, and the final
  outcome are **not** pushed: read them with `GET /public/2025-04-01/disputes/{disputeId}` on your
  own schedule, or from the dashboard. Wider dispute-event coverage is planned.
</Callout>

## `dispute.created` [#dispute-created]

Fires after Chargeflow ingests a new dispute from a connected PSP and completes its first enrichment pass - so the payload already shows what Chargeflow matched, and you can focus on the gaps.

**What to do:** inspect the linked objects (`transaction`, `order`, `subscription`, `customerCommunication`), gather any missing high-impact data from your systems, then `PATCH` the dispute using `data.id`. See [Enrich a dispute](https://docs.chargeflow.io/docs/merchants/automation/enrich-a-dispute) for the endpoint and merge behavior. Payload: [API reference](https://docs.chargeflow.io/docs/api/2025-04-01/merchants/webhooks-events/dispute.created).

## `alerts.created` [#alerts-created]

Fires in real time when Chargeflow ingests a new pre-chargeback alert. Some fields (for example `transaction`) may populate later; for the full record call `GET /public/2025-04-01/alerts/{id}`.

**What to do:** in the automated Chargeflow Alerts model no action is required - use it to trigger supplementary workflows (CRM tagging, fraud notifications). In the merchant-managed model, locate the transaction, refund it, and report the outcome. See [Manage pre-chargeback alerts](https://docs.chargeflow.io/docs/merchants/alerts/manage-alerts). Payload: [API reference](https://docs.chargeflow.io/docs/api/2025-04-01/merchants/webhooks-events/alerts.created).

## `alerts.updated` [#alerts-updated]

Fires whenever Chargeflow updates an alert's `outcome`.

| Outcome               | Meaning                                      |
| --------------------- | -------------------------------------------- |
| `prevented`           | Refunded; chargeback prevented               |
| `not_found`           | No matching transaction located              |
| `duplicate`           | Duplicate of an existing alert               |
| `chargebacked`        | Escalated to a chargeback despite mitigation |
| `previously_refunded` | Already refunded before the alert arrived    |
| `pending`             | Still being processed                        |
| `error`               | An error occurred while handling the alert   |

**What to do:** sync your records to the outcome. On `prevented`, record the win and close tickets; on `chargebacked`, watch for `dispute.created` to begin enrichment; on `not_found`, investigate manually; `duplicate` / `previously_refunded` need no action. Payload: [API reference](https://docs.chargeflow.io/docs/api/2025-04-01/merchants/webhooks-events/alerts.updated).

## `alerts.transaction.linked` [#alerts-transaction-linked]

Fires when Chargeflow matches an alert to a PSP transaction using card metadata (amount, BIN, last 4, auth code, ARN). Not every alert produces this event - if no match is found automatically, it does not fire.

**What to do:** informational in the automated model. In merchant-managed mode it supplies the `transactionId` to refund before you report the outcome - subscribe to both `alerts.created` and this event, since some alerts carry the transaction on creation and others only here. See [Manage pre-chargeback alerts](https://docs.chargeflow.io/docs/merchants/alerts/manage-alerts). Payload: [API reference](https://docs.chargeflow.io/docs/api/2025-04-01/merchants/webhooks-events/alerts.transaction.linked).

## Next step [#next-step]

<Card title="Subscribe to webhook events" href="/docs/merchants/automation/subscribe-to-events">
  Register an endpoint, verify signatures, and build your handler.
</Card>