Merchant webhook events
The four merchant webhook events - dispute.created and the three alerts events - with when each fires, what to do, and where to find the payload.
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; this page is the narrative catalog - when each event fires and what to do with it.
Available events
| Event | Fires when | What to do |
|---|---|---|
dispute.created | A new dispute is ingested and first-pass enriched | Trigger your enrichment flow |
alerts.created | A new pre-chargeback alert arrives | Refund / mitigate (or trigger workflows) |
alerts.updated | An alert's outcome changes | Sync your records to the new outcome |
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. For signature verification and delivery/retry behavior, see Webhooks.
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.
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 for the endpoint and merge behavior. Payload: API reference.
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. Payload: API reference.
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.
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. Payload: API reference.