• How it works
  • GraphQL mutations
  • Topics with sub-topics

About sub-topics

Caution

Sub-topics are deprecated as of the 2024-07 version of the Admin APIs.

metaobjects/create, metaobjects/delete, metaobjects/update topics now require you to filters instead. To do this, you can update your webhook subscription by replacing subTopic with filter everywhere.

Note that you must explicitly utilize each metaobject definition's name when using filters across all definitions. For example: "filter": "type:banana" AND "type:apple" and NOT "filter": "type:*".

Learn more about working with webhook filters.

Webhook sub-topics are an extra level of grouping available for some webhook topics. Sub-topics work with topics to enable delivery of a more specific and relevant stream of webhooks to your app.

How it works

Anchor link to section titled "How it works"

When you subscribe to some webhook topics, your app can specify a sub-topic. Your app will then only receive webhooks for both the topic and sub-topic it subscribed to. Each topic uses its own scheme for allocating sub-topics. The following diagram illustrates the relationship between topics, sub-topics, webhooks, and subscriptions:

An overview showing the relationship between topics, sub-topics, webhooks, and subscriptions

GraphQL mutations

Anchor link to section titled "GraphQL mutations"

Sub-topics are available in API version 2024-01 and higher. You can use the following GraphQL Admin API mutations to subscribe to a webhook with sub-topics:

  • webhookSubscriptionCreate
  • pubSubWebhookSubscriptionCreate
  • eventBridgeWebhookSubscriptionCreate

Topics with sub-topics

Anchor link to section titled "Topics with sub-topics"

The following topics support sub-topics.

Metaobjects

Anchor link to section titled "Metaobjects"
  • Topics: metaobjects/create, metaobjects/update, metaobjects/delete
  • Sub-topics: Required
  • Scheme: Sub-topics map to metaobject definitions
  • Format: type:{type}, using the type of the metaobject definition
  • Considerations:
    • For app-owned metaobject definitions, you can't use the $app:{some-namespace} shorthand when specifying a sub-topic. Use the full type value, as it appears in query responses: app--{your-app-id}--{some-namespace}

On this page

  • How it works
  • GraphQL mutations
  • Topics with sub-topics