Skip to content

[Feature] Add filter field support to webhook handlers#3197

Open
vsmityukh wants to merge 5 commits intoShopify:mainfrom
vsmityukh:feat/webhook-filter-support
Open

[Feature] Add filter field support to webhook handlers#3197
vsmityukh wants to merge 5 commits intoShopify:mainfrom
vsmityukh:feat/webhook-filter-support

Conversation

@vsmityukh
Copy link
Copy Markdown

[Feature] Add filter field support to webhook handlers

WHY are these changes introduced?

Shopify's GraphQL Admin API supports a filter parameter on webhook
subscriptions (WebhookSubscriptionInput.filter) that limits which
payloads get delivered based on a filter expression (e.g. "title:shoes").
The library already supports analogous fields — includeFields and
metafieldNamespaces — but filter was never wired up, making it
impossible to use this API capability through the SDK.

WHAT is this pull request doing?

Adds filter?: string support to webhook handlers, following the exact
same pattern as includeFields and metafieldNamespaces:

  • types.ts: Added filter?: string to BaseWebhookHandler (inherited
    by all three delivery methods) and to WebhookCheckResponseNode (the shape
    returned by Shopify when listing existing subscriptions)
  • register.ts:
    • TEMPLATE_GET_HANDLERS now queries the filter field from Shopify
    • buildHandlerFromNode reads filter from the existing subscription node
    • areHandlerFieldsEqual compares filter when deciding whether an update
      is needed
    • buildMutation serializes filter into the GraphQL mutation params
  • __tests__/responses.ts: Added webhookCheckResponseWithFilter fixture
  • __tests__/register.test.ts: Three new test cases:
    • Sends filter in a create mutation when the handler has it set
    • Triggers an update mutation when the filter value changes
    • Skips the mutation entirely when the filter is unchanged
  • docs/reference/webhooks/addHandlers.md: Documented the new filter
    parameter with a link to the Shopify API reference

Type of change

  • Patch: Bug (non-breaking change which fixes an issue)
  • Minor: New feature (non-breaking change which adds functionality)
  • Major: Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

  • I have used pnpm changeset to create a draft changelog entry (do NOT update the CHANGELOG.md files manually)
  • I have added/updated tests for this change
  • I have documented new APIs/updated the documentation for modified APIs (for public APIs)

@github-actions github-actions Bot added cla-needed devtools-gardener Post the issue or PR to Slack for the gardener labels Apr 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

devtools-gardener Post the issue or PR to Slack for the gardener

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant