Shopify Webhook Reference Redesign

BACKGROUND

Shopify’s developer documentation serves as a key resource that drives scalability, reliability, and innovation across its platform, benefiting both the company and its vast developer community.

Effective documentation should be easily accessible, visually intuitive, and comprehensive - a standard that the Shopify Dev Docs design team prioritizes to enhance the user experience for developers.

THE PROBLEM

The team initially decided to redesign the REST webhook reference pages for several reasons:
‍
• The treatment of the topics list left out important information and wasn’t visually straightforward
• Sample payloads were buried inline which made them hard to find and read
• The mandatory webhooks section was displayed inaccurately
• There was no indication of which content included personally identifiable information

With these issues in mind, I went on to redesign parts of this page to address these problems.

WEBHOOK TOPICS LIST

Previously, the webhook topics list needed some love. The table was difficult to parse through because the contents didn’t always line up, causing inefficiency and leaving room for unintended misinformation. On mobile, half of the code snippets were cut off the screen. There was no mention of important details like resource or access scopes, and the placement of the table was in an unrelated section, causing confusion for developers.

Now, with a new section dedicated to the full list of webhook topics, it’s easier for developers to find the webhook that they’re looking for. For each webhook topic, developers can view a description, the associated resource and appropriate access scope needed, as well as the payload.By keeping the list fully expanded, it’s CMD+F friendly, allowing developers to efficiently find out more about a known topic they are looking for. For the explorer developers without a known topic, the list is easily discoverable through the link in the topics section of the webhook object properties list, or through the side nav.The lengthy section will be the last on the page, so it will not obstruct the user’s navigation. Also, unlike the previous version of the webhook page, this one is fully responsive on mobile devices.

MANDATORY WEBHOOKS

Previously, the mandatory webhooks section was inaccurate and confusing. Instead of showing the mandatory webhooks, it showed the full list of webhooks as if they were all mandatory.

Now, with a new section dedicated to the full list of webhook topics, it’s easier for developers to find the webhook that they’re looking for. For each webhook topic, developers can view a description, the associated resource and appropriate access scope needed, as well as the payload.

By keeping the list fully expanded, it’s CMD+F friendly, allowing developers to efficiently find out more about a known topic they are looking for. For the explorer developers without a known topic, the list is easily discoverable through the link in the topics section of the webhook object properties list, or through the side nav.

The lengthy section will be the last on the page, so it will not obstruct the user’s navigation. Also, unlike the previous version of the webhook page, this one is fully responsive on mobile devices.

PERSONALLY IDENTIFIABLE INFORMATION

Personally identifiable information is protected customer data that needs special permissions and mandatory requirements followed in order to access. This reference page was created before the PII project was established, so it hadn’t been designed to include that kind of information. This left developers with incomplete information about the structure and content of the webhook payloads they received.

We’re now making the recommendation that webhook topics be identified when they require personally identifiable information, so that users are made aware of any omissions and informed of the processes they must complete in order to view the full codeblock. Any content containing PII is marked with the shield icon. Simply hover for an explanation and click to learn more in another tab.

SUBSEQUENT GRAPHQL WEBHOOK REFERENCE REDESIGN

Following the completion of the REST reference page redesign, its GraphQL counterpart also had to be updated. To allow for consistency, design components made for the REST webhook page were reusable here. Any other small changes made were intentional in preserving the design and IA patterns specific to the GraphQL reference pages.

CONTENT GUIDELINES

After conducting primary research through workshops with internal developers, the need for more granularity within topic descriptions was discovered. To ensure consistency and structure for the various teams writing descriptions, a set of guidelines were created and shared as part of the project. This allows for the inclusion of more detailed information, such as the mention of post-populated fields that do not belong on the resource reference page itself.

CONCLUSION AND NEXT STEPS

With the implementation of these changes, developers should have an easier time navigating the webhook reference pages, which could in turn help facilitate their application of useful automations in the things that they build.

For next steps, I’d personally like to keep an eye out for feedback on this page moving forward. I’m also on the lookout for similarly long lists like this. If this is a common pattern, it may be worth it in the future to alter search behaviours to automatically find and open collapsed sections that contain the search query, to maximize space efficiency without impeding findability.

As a final note, I want to express how much of a great experience spearheading this project was and I'm grateful to everyone who’s provided me with context along the way.

Check out the REST redesign live on Shopify's developer documentation site.