Platform webhook events
The platform webhook events - evidence.ready, evidence.error, and integration.access.error - with when each fires, what to do, and where to find the payload.
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; this page is the narrative catalog - when each event fires and what to do. For signature verification and delivery/retry behavior, see Webhooks.
Available events
| Event | Fires when | What to do |
|---|---|---|
evidence.ready | An evidence PDF is generated | Download and submit it to your PSP |
evidence.error | Generation fails after all retries | Read the error code, fix, retry |
integration.access.error | Chargeflow loses access to a merchant PSP | Get the merchant to reconnect |
dispute.created | A dispute is ingested for a merchant | Schema in the API reference |
evidence.ready
Fired when an EaaS evidence PDF has been generated and is available to download.
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.
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.
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.
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 integrations.
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.
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.