# Manage pre-chargeback alerts (https://docs.chargeflow.io/docs/merchants/alerts/manage-alerts)
You want complaints resolved before they post as chargebacks, with the alert data flowing through your own systems. This guide covers the **Alerts API**: choosing an integration model, the endpoints, and the outcome vocabulary. For the product overview, start at the [Alerts landing page](https://docs.chargeflow.io/docs/merchants/alerts); the integration models are taught canonically in [Alerts model](https://docs.chargeflow.io/docs/reference/concepts/alerts-model).
## How alerts work [#how-alerts-work]
Card networks issue a pre-chargeback alert when a cardholder questions a transaction,
giving you a short window (typically 24-72 hours) to refund and stop the chargeback from
posting. The end-to-end flow and the two integration models - **Chargeflow Alerts** (full
automation) and **merchant-managed** (you issue the refund) - are covered in
[Alerts model](https://docs.chargeflow.io/docs/reference/concepts/alerts-model). This guide is the API-level how-to:
the endpoints, the webhooks, and the merchant-managed outcome flow.
Want the alerts delivered to your systems without Chargeflow touching the money? That is
merchant-managed handling: you receive every alert over the API and webhooks, issue the refund
(or decline) in your own processor, and report the result back. The
[steps below](#merchant-managed-step-by-step-responsibilities) are what your side owns.
## Available endpoints [#available-endpoints]
| Endpoint | Method | Description |
| ---------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `/public/2025-04-01/alerts` | GET | Retrieve a paginated list of all alerts for your account. Supports filtering by date, type, status, and reason. |
| `/public/2025-04-01/alerts/{id}` | GET | Retrieve full details of a specific alert by its ID, including status, outcome, and transaction details. |
| `/public/2025-04-01/alerts/{id}/outcome` | POST | Update the outcome for a specific alert. Required when using Merchant-Managed Handling. |
Read access to the Alerts endpoints is enabled per account, and working webhook delivery does not
grant it. If a key that passes the [health
check](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling#health-check-endpoint) still gets `403`
here, ask [Support](https://docs.chargeflow.io/docs/reference/support) to enable it.
## Available webhooks [#available-webhooks]
| Webhook | Trigger | Description |
| --------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `alerts.created` | A new pre-chargeback alert is received | Sends an HTTP POST to your endpoint with the alert ID and metadata. Use this to initiate refunds or other mitigation actions. |
| `alerts.transaction.linked` | Chargeflow matches an alert to a transaction | Sends an HTTP POST with the alert ID and matched transaction ID. Useful if you need transaction-level data for your automated processes. |
| `alerts.updated` | The outcome of an alert is updated | Sends an HTTP POST with the updated outcome and timestamp. |
## Merchant-Managed: step-by-step responsibilities [#merchant-managed-step-by-step-responsibilities]
If you are using the Merchant-Managed model, your system must complete the following steps for each alert:
### Receive the alert [#receive-the-alert]
Listen for `alerts.created` on your webhook endpoint. The payload includes the alert ID and metadata. If you need the matched PSP transaction ID before taking action, also subscribe to `alerts.transaction.linked`.
### Locate and validate the transaction [#locate-and-validate-the-transaction]
Using the alert metadata (amount, currency, card details, ARN), find the corresponding transaction in your payment processor or order management system.
### Issue the refund [#issue-the-refund]
Process the refund in your payment processor. Keep a record of the refund confirmation.
### Report the outcome to Chargeflow [#report-the-outcome-to-chargeflow]
Call `POST /public/2025-04-01/alerts/{id}/outcome` with the result. This step is critical: without it, Chargeflow cannot report back to the issuer and the chargeback may still be filed.
```bash title="Terminal"
curl -X POST https://api.chargeflow.io/public/2025-04-01/alerts/ALERT_ID/outcome \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"outcome": "refunded"}'
```
Failing to call the outcome endpoint in Merchant-Managed mode means Chargeflow cannot close the alert with the issuer. Always report outcomes, even if the transaction was already refunded (`previously_refunded`).
## Outcome vocabularies [#outcome-vocabularies]
Alert outcomes use two distinct vocabularies. The value you **post** to the outcome endpoint is not the same set you **receive** on the `alerts.updated` webhook.
**Outcome you POST** to `POST /alerts/{id}/outcome`:
| Value | Meaning |
| --------------------- | ------------------------------------------------------------------- |
| `refunded` | You refunded the transaction to handle the alert. |
| `previously_refunded` | The transaction had already been refunded before the alert arrived. |
| `duplicate` | The alert duplicates one you have already handled. |
| `decline` | You are declining to refund this alert. |
| `error` | You could not process the alert due to an error. |
**Outcome you RECEIVE** on the `alerts.updated` webhook:
| Value | Meaning |
| --------------------- | -------------------------------------------------------------- |
| `duplicate` | The alert is a duplicate of an existing alert. |
| `not_found` | No matching transaction could be located. |
| `prevented` | The transaction was refunded and the chargeback was prevented. |
| `pending` | The alert is still being processed. |
| `chargebacked` | The alert escalated to a chargeback despite mitigation. |
| `previously_refunded` | The transaction was already refunded before the alert arrived. |
| `error` | An error occurred while handling the alert. |
## Next steps [#next-steps]
How to register for alert webhooks.
Payload reference.
Payload reference.
Payload reference.