`orders/create` `source_name` value for Headless storefront orders

Hydrogen and Storefront APIs
1

Description:

Our app registers an orders/create webhook and previously filtered Online Store orders by checking source_name === "web". However, one of our clients is now using a headless storefront (built with Hydrogen/Storefront API), and we’ve noticed the source_name value has changed from "web" to a numeric ID like "121xxxx". This has broken our filtering logic and made it unclear how to detect orders from headless storefronts.

What I’ve Tried:

  • Queried recent orders using the GraphQL Admin API to inspect sourceName.
  • Retrieved the associated channelInformation.channelDefinition.channelName, which showed "Headless" for the sourceName in question.

Questions:

  1. Is there any official documentation on the meaning or structure of source_name in the orders/create webhook payload? I found this old Community thread, but it appears outdated.
  2. Is it safe to hardcode a mapping between a numeric source_name (e.g. 121xxxx) and "Headless" based on what we get from the GraphQL API?
  3. Is the GraphQL Admin API (specifically order.sourceName and channelInformation.channelDefinition.channelName) the only way to resolve these values into something human-readable?
  4. I can use source_name === "web" to reliably identify Online Store orders. But is there a standard or reliable way to detect orders from a headless storefront (e.g. Storefront API, Hydrogen) within webhook payloads?

Any advice or best practices would be greatly appreciated!

1 Like
2

Hey @joel - I was able to replicate what you’re seeing here. It does look like when it comes to Headless sales channels, we will return a numerical source_name ID. It looks like we can run a query that would the human readable sales channel information though. This would need to be on the orders object (just using my Headless channel’s source_name value):

{
orders (first:10, reverse:true, query:"source_name:16154930*") {
  nodes {
    id
    sourceName
    sourceIdentifier
    app {
      id
      name
    }
  }
}
}

Here’s what I get when I query that, just as an example:

image
image1599×354 37.1 KB

This may work as a workaround for now (for example, when your app first receives a webhook payload for an order with a numerical source_name, it could then run something like the above, and extract the app name/confirm if it’s “Hydrogen”/“Headless”, etc and then store that info to match correctly with the filter on a store by store/app by app basis (since each shop could have multiple Hydrogen/Headless storefronts with different IDs).

It’s definitely not ideal though, so I’m happy to speak with some folks internally to see if we can clarify things for you or at the very least log a feature request.

Speak with you as soon as I have more info on my end here!

4

Hey again @joel, I was able to touch base with the product team on this, and can confirm that you should be good to hardcode the numeric ID as a workaround for your filtering logic.

The one caveat there is that this would only work if a shop is running a single headless/Hydrogen storefront. For most merchants, this is the case, but I did want to mention that as one common limitation.

That said, I also get that this isn’t the most ideal set up, so I’m going to write up a feature request on my end so that we can look linto making the naming conventions for the source values on Headless storefront sales channels a bit more human readable/clear. I can’t guarantee anything on my end, but I do agree this would make things much easier for use cases like yours. Let me know if I can include any other info on my end in the feature request, happy to help out further if needed!