Register your webhook endpoint for charge.dispute.created, charge.dispute.updated, charge.dispute.funds_withdrawn, and charge.dispute.closed events
On charge.dispute.created, extract the dispute.id, dispute.reason, dispute.evidence_details.due_by, and the original charge.id; immediately look up the order in your system using the charge metadata or payment intent
Automatically pull relevant evidence from your internal systems: customer email, shipping tracking number, order receipt, and IP address used at checkout; store these against the dispute record
If the dispute can be resolved automatically (e.g. refund was already issued before the dispute), submit evidence immediately with the refund documentation and a clear explanation
On charge.dispute.closed, check dispute.status: won means funds are returned; lost means funds remain with the customer and the dispute fee is kept; use this to update your internal ledger
Known gotchas
charge.dispute.created fires even when you accept the dispute; do not assume that receiving this event means you must contest it
The dispute evidence due_by deadline in the webhook payload is in UTC; convert it to your timezone for human-readable alerts to avoid missing the deadline due to timezone confusion
Stripe may send multiple charge.dispute.updated events as the dispute progresses through network stages; deduplicate by dispute status rather than event count
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?