Shopify Dispute Webhooks: Subscribe to Creation and Update Events

Subscribe to both dispute creation and dispute update events so your monitoring integration learns about new cases and later changes. Treat each accepted notification as a reason to refresh the current case from Shopify. Do not assume the payload is a complete, permanently authoritative copy of everything your interface needs.

The illustrative configuration below targets Shopify webhook API version 2026-07, the stable version reviewed on 6 September 2026. It has not been deployed to a live app. Validate the configuration and the authorized store's scope before relying on production events.

Use the documented topic names

The Admin GraphQL topic enum contains DISPUTES_CREATE and DISPUTES_UPDATE. Their configuration topic strings are disputes/create and disputes/update. Shopify documents the names and required dispute read scope in the webhook topic reference.

[webhooks]
api_version = "2026-07"

[[webhooks.subscriptions]]
topics = ["disputes/create", "disputes/update"]
uri = "/webhooks/disputes"

This is an app-configuration example. Follow Shopify's subscription setup guidance for the delivery method and deployment workflow your app uses. Do not create a second overlapping subscription without understanding the resulting deliveries.

The configuration says which notifications you want. It does not grant the app access to read disputes or prove that the merchant has authorized the installation. Verify those conditions separately.

Define the receiver's narrow responsibility

The receiver should authenticate the delivery, identify the installed shop and accepted topic, and place the required refresh work in durable storage. It should avoid doing a full case synchronization before acknowledging receipt.

Use the documented payload for the selected version to obtain the dispute reference. Do not guess that every numeric field is a GraphQL ID or concatenate an arbitrary value into an identifier without validating the documented mapping.

The work item should contain your internal installation identity, the source case reference, topic and safe correlation metadata. It does not need customer contact information merely to request a later refresh.

Keep transport acceptance separate from successful case refresh. If a notification is accepted but the API read later fails, the case should remain queued or visibly stale under your worker's failure policy.

Refresh the current case after notification

Shopify's dispute query reference provides the supported case lookup. Use it through the same authorized installation that received the event.

The monitoring update should store current status, amount, currency, reason and available deadline from the source response. A creation event and an update event can both request this same read path.

This design avoids writing a different permanent case model for each webhook payload shape. It also reduces the temptation to infer a final outcome from the topic name. disputes/update indicates a change notification; the refreshed case establishes the current state.

A worker must still handle a temporarily unavailable or inaccessible case. Do not delete an existing local case because one refresh returns an error. Record the failure and use the appropriate follow-up path.

Walk through a hypothetical event sequence

A hypothetical merchant receives a new dispute. Shopify sends the creation notification, the receiver authenticates it and the worker retrieves the case. The inbox displays the source status and deadline with a last-successful-refresh time.

Later, Shopify sends an update notification. The same refresh path retrieves the current case and updates the operational record. The application does not assume the event means “won,” “lost” or “submitted”; it reads the actual state.

If the merchant has no disputes, a quiet endpoint is not proof that subscriptions are missing. Verify the deployed configuration and available subscription diagnostics. Do not create a real chargeback to generate traffic.

If a test tool supplies a sample payload, use it to inspect routing and parsing only within its supported limits. A successful synthetic request does not prove production merchant authorization or current source access.

Verify registration and interpretation separately

Use this acceptance checklist for the initial implementation:

The checklist deliberately separates a registered subscription from a working monitoring result. Both are needed.

Do not add financial actions to the receiver simply because it knows a dispute changed. A monitoring notification should lead to an accurate view and a merchant-owned decision through the appropriate workflow.

Finally, record how operators can identify the source case and check it in Shopify. Correct topic selection is the first step; the operational value comes from turning each authenticated event into a traceable refresh of the underlying dispute.

Explore monitored dispute information while checking your store's authorized connection.

Explore the Shopify app

Related reading in this collection:

• Query Shopify Payments Disputes With GraphQL: A Monitoring-Only Example
• Uninstall and Privacy Webhooks in a Shopify Dispute App
• Verify Shopify Dispute Webhook Signatures Before Processing Events