# Platform webhook events (https://docs.chargeflow.io/docs/platforms/webhook-events)



Chargeflow pushes real-time notifications to your platform when key events occur. Formal payload schemas are generated from the spec and live in the [API reference](https://docs.chargeflow.io/docs/api/2025-04-01/platforms/webhooks-events); this page is the narrative catalog - when each event fires and what to do. For signature verification and delivery/retry behavior, see [Webhooks](https://docs.chargeflow.io/docs/reference/concepts/webhooks).

## Available events [#available-events]

| Event                                                                               | Fires when                                | What to do                         |
| ----------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------- |
| [`evidence.ready`](#evidence-ready)                                                 | An evidence PDF is generated              | Download and submit it to your PSP |
| [`evidence.error`](#evidence-error)                                                 | Generation fails after all retries        | Read the error code, fix, retry    |
| [`integration.access.error`](#integration-access-error)                             | Chargeflow loses access to a merchant PSP | Get the merchant to reconnect      |
| [`dispute.created`](https://docs.chargeflow.io/docs/api/2025-04-01/platforms/webhooks-events/dispute.created) | A dispute is ingested for a merchant      | Schema in the API reference        |

## `evidence.ready` [#evidence-ready]

Fired when an EaaS evidence PDF has been generated and is available to download.

<Callout type="warn" title="Warning">
  `file_url` expires **7 days** after it is issued. Store the `evidence.id`, not the URL; call the
  evidence API with the id for a fresh link.
</Callout>

**What to do:** (1) verify the `x-chargeflow-hmac-sha256` signature; (2) download the `file_url` and store the PDF; (3) submit it to your PSP before `due_by`; (4) optionally surface an "evidence ready" status to the merchant. Regeneration re-fires this event with an incremented `file_version` (same `evidence.id`). Payload: [API reference](https://docs.chargeflow.io/docs/api/2025-04-01/platforms/webhooks-events/evidence.ready).

## `evidence.error` [#evidence-error]

Fired when generation fails after all automatic retries. Chargeflow will not retry further until you call the Generate Evidence API again.

| Error code                   | Cause                           | Resolution                                                                   |
| ---------------------------- | ------------------------------- | ---------------------------------------------------------------------------- |
| `422_dispute_invalid_state`  | Dispute not in `needs_response` | If it moved to `under_review` / `won` / `lost`, generation no longer applies |
| `409_generation_in_progress` | A generation is already running | Wait for `evidence.ready` / `evidence.error`                                 |
| `404_*_not_found`            | Dispute not found               | Verify `dispute_id` + `account_id` match                                     |
| `403_eaas_not_enabled`       | Key not entitled to EaaS        | Contact your account manager                                                 |
| `504_generation_timeout`     | Transient AI timeout            | Retry the request                                                            |

**What to do:** verify the signature, read `error_code`, fix the underlying issue, then retry `POST /public/2025-04-01/evidence`. Payload: [API reference](https://docs.chargeflow.io/docs/api/2025-04-01/platforms/webhooks-events/evidence.error).

## `integration.access.error` [#integration-access-error]

Fired when Chargeflow cannot access a merchant's PSP or data source - usually expired, revoked, or changed credentials. Relevant primarily for [White-Label](https://docs.chargeflow.io/docs/platforms/chargeflow-embedded/overview) integrations.

<Callout type="warn" title="Warning">
  While the integration is broken, Chargeflow cannot ingest or enrich disputes for this merchant.
  Cases may be missed or processed with incomplete data until it is restored.
</Callout>

**What to do:** (1) verify the signature; (2) identify the merchant via `integration.account_id` / `integration.ext_account_id`; (3) notify them that their `integration.provider` connection broke; (4) guide them to re-authorize. Common causes: rotated/revoked PSP keys, expired OAuth tokens (Shopify, WooCommerce), or a suspended PSP account. Payload: [API reference](https://docs.chargeflow.io/docs/api/2025-04-01/platforms/webhooks-events/integration.access.error).

## Next step [#next-step]

<Card title="Generate & regenerate evidence" href="/docs/platforms/eaas/generate-and-regenerate">
  The API call these events report on.
</Card>