Webhook payloads are not sufficiently documented

Shopify Apps

Topic summary

Shopify’s webhook payload documentation relies solely on single response samples, which is insufficient for maintaining robust apps. This approach creates several problems:

Key Issues Identified:

  • Developers must infer data types from limited examples, making it time-consuming and error-prone
  • Alternative values and edge cases aren’t visible in samples
  • Response payloads contain extra fields not mentioned in documentation
  • Null values in samples prevent determining actual data types
  • Shopify’s AI assistant provides incorrect information about webhook types

Specific Examples:

  • Product webhook documentation doesn’t match actual response structure
  • app_subscription/update webhook inconsistently returns data shown in documentation

Unanswered Questions:

  • Multiple community posts and GitHub issues remain unresolved
  • No clarity on whether comprehensive type definitions will be published

The developer requests official type definitions, noting these must exist internally since webhooks are already publicly available. The discussion remains open with no response from Shopify.

Summarized with AI on October 29. AI used: claude-sonnet-4-5-20250929.
1

Curently, webhook payload documentation is solely a single response sample. This is not enough

to keep a well maintained app. Other places where I searched (online posts, official library repositories,

this forum, and other docs), either don’t have information or have questions unsolved:

https://community.shopify.com/c/webhooks-and-events/where-can-i-find-docs-for-webhooks-types/m-p/2081023

https://github.com/Shopify/shopify-api-js/issues/359

Relying on a single sample to infer types is time-consuming, error-prone, inconvenient, hard (as other

alternative values can’t be seen). In addition to this, sample mentions resources, but the responses

include extra fields. Take the product webhook for instance.

Finally, a last problem that I found is that the AI assistant at https://shopify.dev/docs/ provide incorrect

answers regarding these types.

I would like to know if there are plans for publishing (as they must have been implemented prior to releasing

the webhooks to the public, necessarily) them.

Thanks

2 Likes
2

Even more, the app_subscription/update webhook does not always retrieve all the data shown in the documentation.

It is very important to have such cases documented.

Also, the sample responses show null values that do not allow to get the value type.