Module shopify.trigger
ballerinax/shopify.trigger Ballerina library
Overview
The Ballerina listener for Shopify allows you to listen to store events, grouped by the resource they relate to.
- Orders (
OrdersService):onOrdersCreate,onOrdersUpdated,onOrdersCancelled,onOrdersFulfilled,onOrdersPartiallyFulfilled,onOrdersPaid - Customers (
CustomersService):onCustomersCreate,onCustomersUpdate,onCustomersEnable,onCustomersDisable,onCustomersMarketingConsentUpdate - Products (
ProductsService):onProductsCreate,onProductsUpdate - Fulfillments (
FulfillmentsService):onFulfillmentsCreate,onFulfillmentsUpdate
This module receives Shopify's webhook notifications directly - it does not call Shopify's Admin API
on your behalf. Each notification carries the full resource representation (the whole order, customer,
product, or fulfillment), not just a change reference, so no follow-up API call is needed to see what
changed. A subscription that sets include_fields gets only the fields it lists; fetch anything else
with the Admin API.
Key features
- Receives 15 Shopify events for orders, customers, products and fulfillments
- Verifies every delivery with the app's client secret (HMAC-SHA256,
X-Shopify-Hmac-Sha256) - Typed payload records carrying the full order, customer, product or fulfillment (or the fields a
subscription picks with
include_fields) - Acknowledges each delivery before running your handler, so a slow or failing handler doesn't cause retries
- Services can be attached on their own path, so several triggers and HTTP services can share one port
- Trigger services are listed by
bal build --export-endpoints(Ballerina 2201.13.6 or later)
Setup guide
Before using this connector in your Ballerina application, you need a Shopify partner account and a development store to generate real events against, and a Ballerina service that Shopify can reach over the internet to deliver webhook payloads to. The two sections below cover both a quick local test setup and a production deployment.
Try it out locally
Use this flow to test your webhook handling logic on your own machine before deploying anywhere, using ngrok to expose your local listener to the internet.
Step 1: Create a Shopify Partner account and a development store
-
Sign up for a Shopify Partner account if you don't already have one.
-
From the Partner Dashboard, go to Stores > Create store > Dev and create a development store - this is where you'll trigger real test events (creating orders, customers, products, etc.). Turn on Generate test data for store so you have sample products and a bogus payment gateway ready to go.
Step 2: Create a custom app
Shopify's older "legacy custom apps" flow (configured directly under a store's Settings) has been retired. Apps are now created and managed through the Dev Dashboard, and webhook subscriptions are declared as config rather than filled into a form.
-
From the Partner Dashboard, go to Apps > Create app, give it a name, and leave the app URL as a placeholder (e.g.
https://example.com) - it's only relevant for an app with a real embedded UI, which this test app doesn't need.
-
Install the Shopify CLI (
npx shopifyworks without a global install) and link a local project to the app you just created:npx shopify app config linkThis logs you into the Shopify CLI (opens a browser) and prompts you to select your organization and the app to link to, generating a
shopify.app.tomlfile in the current directory.
Step 3: Set up ngrok
The Ballerina listener runs locally and needs a publicly accessible URL so Shopify can deliver webhook events to it. ngrok creates a secure tunnel from a public URL to your local service.
Install ngrok and start a tunnel on port 8090 (the default port for the Ballerina listener):
ngrok http 8090
Copy the HTTPS forwarding URL from the ngrok terminal output. It looks like:
https://xxxx-xxx-xxx-xxx.ngrok-free.app
Save this value - you will need the ngrok URL in the next step.
Step 4: Subscribe to webhook topics
Add the topics you want to receive to shopify.app.toml, pointing at your ngrok URL from Step 3,
and declare the access scope each topic needs (e.g. products/create needs read_products). Keep
the [webhooks] table and its api_version that app config link wrote; Shopify requires it:
[access_scopes] scopes = "read_products" [webhooks] api_version = "<the version app config link wrote>" [[webhooks.subscriptions]] topics = ["products/create"] uri = "<your ngrok URL, e.g. https://abc123.ngrok-free.app>"
Some topics (e.g. anything under
orders/*orcustomers/*) touch protected customer data and require Shopify's separate data-access approval before you can subscribe to them - see Protected customer data if you hit that error. Fulfillment topics can also count as protected customer data, since they carry the customer's email and shipping destination.products/*has no such restriction and is the simplest topic to test locally.
Deploy the config:
npx shopify app deploy
Deploying doesn't install the app. Install it on your development store from the app's page in the Dev Dashboard (Install app, then pick the development store).
Confirm the subscription is live from the app's Versions page in the Dev Dashboard:
Repeat with more [[webhooks.subscriptions]] blocks for every additional topic your service needs.
Step 5: Retrieve the signing secret
Shopify signs every webhook delivery with your app's Client Secret, using HMAC-SHA256 over the raw request body. This is a single shared secret - unlike QuickBooks' separate verifier token, it's the same credential used to sign every subscription on the app.
-
Go to the app's App settings page in the Dev Dashboard and reveal the Client secret.
Save this value - you will need it in the Quickstart section when initialising the Ballerina listener. This is the value the listener calls
webhookSecret.
Production / business integration
The steps above use ngrok's temporary URL, which is fine for local testing but not for a real deployment. For production use:
-
Deploy your Ballerina service somewhere with a stable, internet-reachable HTTPS URL. Ballerina doesn't require any specific hosting platform - containers, a VM, a managed PaaS, or anything else that gives you a stable HTTPS endpoint all work equally well.
-
Update the
uriin each[[webhooks.subscriptions]]block inshopify.app.toml(Step 4) to your production URL instead of the ngrok URL, and runshopify app deployagain to push the change live. -
Rather than hardcoding
webhookSecretas shown in the Quickstart, inject it viaConfig.toml(or your platform's equivalent configuration/secret mechanism), since it's aconfigurablevalue. -
If you need topics under
orders/*orcustomers/*, request Shopify's protected customer data approval before going live - see Protected customer data.
Compatibility
| Version | |
|---|---|
| Ballerina Language | Ballerina Swan Lake 2201.13.0 |
Quickstart
To use the Shopify listener in your Ballerina application, update the .bal file as follows.
Before running the quickstart, ensure you have:
- The Client Secret from Step 5 of the Setup guide
- ngrok running ()
ngrok http 8090
Step 1: Import listener
To import the ballerinax/shopify.trigger module into the Ballerina project, add the following statement:
import ballerinax/shopify.trigger as shopify; import ballerina/io;
Step 2: Create a new listener instance
Add the following to your Config.toml file, replacing the placeholder with the value saved during
the Setup guide:
webhookSecret = "<YOUR_CLIENT_SECRET>"
Then initialise the listener in your .bal file:
configurable string webhookSecret = ?; listener shopify:Listener shopifyWebhook = new ( {webhookSecret}, 8090 );
webhookSecret should always match the Client Secret configured on the Shopify app - this is what
the listener uses to verify incoming payloads actually came from Shopify.
Step 3: Invoke listener triggers
Now let's use the triggers available within the listener.
A service attached to one of the listener's service types must implement all of that type's
remote functions. For example, OrdersService exposes six, covering every order event:
service shopify:OrdersService on shopifyWebhook { remote function onOrdersCreate(shopify:OrderEvent payload) returns error? { io:println(payload); } remote function onOrdersUpdated(shopify:OrderEvent payload) returns error? { io:println(payload); } remote function onOrdersCancelled(shopify:OrderEvent payload) returns error? { io:println(payload); } remote function onOrdersFulfilled(shopify:OrderEvent payload) returns error? { io:println(payload); } remote function onOrdersPartiallyFulfilled(shopify:OrderEvent payload) returns error? { io:println(payload); } remote function onOrdersPaid(shopify:OrderEvent payload) returns error? { io:println(payload); } }
Note: Unlike QuickBooks' notification-only webhooks, Shopify sends the full resource
representation in every event - payload above is the complete order, not just its ID, so no
follow-up API call is needed to see what changed.
To compile and run the Ballerina program, issue the following command:
bal run
To verify it is working, go to your Shopify development store and create an order (or whichever resource matches the topic you subscribed to). You should see the event printed in the Ballerina console output.
Examples
The shopify.trigger module provides practical examples illustrating usage in various scenarios.
Explore these examples,
covering common webhook event handling use cases.
Report issues
To report bugs, request new features, start new discussions, etc., go to the Ballerina Library repository
Useful links
- For more information go to the
shopify.triggerpackage. - See the migration notes for context on this package's move from the asyncapi-triggers monorepo.
- For example demonstrations of the usage, go to Ballerina By Examples.
- Chat live with us via our Discord server.
- Post all technical questions on Stack Overflow with the #ballerina tag.
Import
import ballerinax/shopify.trigger;Other versions
0.9.0