The following topic is invalid: customer.joined_segment / customer.left_segment

Webhooks and Events
1

I’m developing a Shopify app, and while deploying it using shopify app deploy, I’m encountering the following error:

Version couldn't be created.

 - The following topic is invalid: customer.joined_segment
 - The following topic is invalid: customer.left_segment

Here’s my app config TOML file:

...
[webhooks]
api_version = "2025-01"
 [[webhooks.subscriptions]]
 topics = [ "customer.joined_segment", "customer.left_segment"]
 uri = "/webhooks/..."
...

I’m using the webhook API version 2025-01, as these topics are listed under this version.

My shopify CLI version is @shopify/cli/3.73.1 darwin-arm64 node-v23.6.0.

Any insights or solutions would be appreciated!

2

Hi hanmanhui,

If you follow the format in the docs which is customer/joined_segment instead of customer.joined_segment, does this work?

Also if you add another webhook like “app/uninstalled” does this work - it’s possible there’s something specific to the customer webhooks you need to adjust for.

3

No, the same error occurs.

Version couldn’t be created.

  • The following topic is invalid: customer/joined_segment
  • The following topic is invalid: customer/left_segment

I’m already using other webhooks and these works fine.

  • customers/data_request
  • customers/redact
  • shop/redact
  • app/scopes_update
  • app_subscriptions/update
  • app/uninstalled
  • customers/create
  • customers/delete
  • orders/paid
4

It actually looks like these webhooks are not subscribed to via the toml file:

563×203 13.9 KB

Can you use this method instead: Subscribe to a topic using GraphQL Admin API

5

To apply your solution, I created the following GraphQL mutation, but it seems the filter parameter is mandatory:

mutation addSegmentJoinedWebhook {
  webhookSubscriptionCreate(
    topic: CUSTOMER_JOINED_SEGMENT
    webhookSubscription: {
      callbackUrl: "<MY_URL>"
      format: JSON
    }
  ) {
    webhookSubscription {
      id
    }
    userErrors {
      message
      field
    }
  }
}

Result:

{
  "data": {
    "webhookSubscriptionCreate": {
      "webhookSubscription": null,
      "userErrors": [
        {
          "message": "The specified filter is invalid, please ensure you specify the field(s) you wish to filter on.",
          "field": [
            "webhookSubscription"
          ]
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 10,
      "actualQueryCost": 10,
      "throttleStatus": {
        "maximumAvailable": 2000,
        "currentlyAvailable": 1990,
        "restoreRate": 100
      }
    }
  }
}

Could you guide me on which fields I need to include for the filter parameter? Also tried to add by remix app like this but same error occurred.

  ...
  webhooks: {
    CUSTOMER_JOINED_SEGMENT: {
      deliveryMethod: DeliveryMethod.Http,
      callbackUrl:
        "<MY_URL>",
    },
  },
  hooks: {
    afterAuth: async ({ admin, session }) => {
      shopify.registerWebhooks({ session });
    })
  },
  ...

[shopify-app/ERROR] Failed to register webhook | {topic: CUSTOMER_JOINED_SEGMENT, shop:
a2-han-test.myshopify.com, result: {"data":{"webhookSubscriptionCreate":{"userErrors":[{"field":["webhookSubscription"],"message":"The
specified filter is invalid, please ensure you specify the field(s) you wish to filter
...

Additionally, where can I find the document referenced in your screenshot? The documentation I referred to was this one, but it does not mention any restrictions. It seems the documentation requires an update.

6

Hi again,

Shopify requires you to specify the fields you wish to filter on when subscribing to certain webhook topics - so you’ll need to add a filter that matches fields available in the webhook payload. For example, if the payload includes a segment_id field, you can filter by segment_id:12345 to only receive webhooks for that specific segment, eg:

mutation AddSegmentJoinedWebhook {
  webhookSubscriptionCreate(
    topic: CUSTOMER_JOINED_SEGMENT
    webhookSubscription: {
      callbackUrl: "<MY_URL>"
      format: JSON
      filter: "segment_id:12345" # Replace with a valid filter
    }
  ) {
    webhookSubscription {
      id
    }
    userErrors {
      message
      field
    }
  }
}

Also you should make sure your app has the read_customers scope: Shopify API access scopes

7

I noticed that the shopify app webhook trigger command for the CUSTOMER_SEGMENT_JOINED topic involves three fields: shop_id, customer_id, and segment_id.

However, I encountered issues when trying to add filters using the following examples:

- segment_id:451329360047
- shop_id:67737616559
- segment_id:451329360047 AND shop_id:67737616559
- segment_id:451329360047 AND shop_id:67737616559 AND customer_id:8161796620463

Unfortunately, none of these filters worked, and they all resulted in the same errors, even though the IDs used are valid. The required scope of read_customers is also applied.

Could you please provide a working example of how to properly apply filters for this topic? Thank you!

Also all the

8

“shop_id”: “gid://shopify/Shop/1”,
“customer_id”: “gid://shopify/Customer/2”,
“segment_id”: “gid://shopify/Segment/3”
}

HI hanmanhui the value should like this.
and available filter are shop_id,customer_id, segment_id

9

Hello Eric Han. Tried global ID format but the same error occurs.

10

Hi Hanmanhui,

Connecting with the customers product team on this! Will update asap.

1 Like
11

Hi again,

Here’s the format that the product team have suggested, which has been tested to work successfully:

mutation {
  webhookSubscriptionCreate(
    topic: CUSTOMER_LEFT_SEGMENT
    webhookSubscription: {
      filter: “segmentId:\“gid://shopify/Segment/1077327757334\“”
      callbackUrl: “https://webhook.site/15b8ec07-ef55-4bdf-bf65-d71bbf8f47b1”
    }
  ) {
    userErrors {
      field
      message
    }
    webhookSubscription {
      apiVersion {
        displayName
        handle
      }
      id
    }
  }
}
12

I’ve tested the query and it worked! Thank you.

1 Like
13

Awesome! If you have any other questions - please let us know!

14

Hey @Liam-Shopify

I’m having trouble subscribing to this webhook topic using your last suggestion here in the thread, but, using multiple segment IDs like:

segmentId:\"gid://shopify/Segment/1\" OR segmentId:\"gid://shopify/Segment/2\"

This should be possible, right?
Also, I couldn’t create a webhook subscription filtered by a customer ID. Every combination of customer_id/customerId/customer.id with gid string/id number/id string gives the same error “The specified filter is invalid, please ensure you specify the field(s) you wish to filter on.”.

What’s the correct way to do this? it’s not really clear from the docs.

CC @Darryn_Soper

15

I’ve also tried to filter multiple segments with single webhook but didn’t worked.
Now I’m registering webhooks separately for each segment.

16

I don’t believe you can include multiple segments in the same subscription. You could subscribe twice instead (once for each).

17

Unfortunately, I also encountered this problem, and I tried the method provided but it failed. My API version is 2025-01. Is there any other solution?

18

@Boxuan_Wang can you confirm the exact error message you’re receiving? Also if you could confirm your app has the customers access scope and provide the filter you are attempting to subscribe with that would be great, thanks!

19

Would it be possible to have a generic CUSTOMER_JOINED_SEGMENT and CUSTOMER_LEFT_SEGMENT where we DO NOT specify any customer_id and segment_id? Some of my merchants have like ~700K customers, it is not practical to register all of them in this way.