Kartik Luke Singh

Shopify Events: only hearing about the updates you care about

2026-09-29T00:00:00Z

At Artos Software we build STOQ, a Shopify app for pre-orders and back-in-stock alerts. To keep pre-orders and alert-driven orders in sync, we listened to the orders/updated webhook. The trouble is that Shopify sends that webhook for every change to every order on a shop, and we only care about a sliver of them. So we moved to Shopify's Events subscriptions,¹ which run a GraphQL query for each change and can filter deliveries based on the response, and let Shopify throw away the rest before it ever reaches us.

Why were we getting 6 million webhooks a day?

A webhook subscription can't filter by order. Every edit, tag, fulfilment and refund on every order became a delivery, a queued job, and a database lookup that usually found nothing and returned. Roughly 350 of our largest shops sent over 60% of that traffic. A busy merchant working through orders all day generated millions of jobs that just got ignored. And that's just the average. Plenty of merchants use bulk-editing apps to tag or update thousands of orders at once, and every one of those edits is another webhook, so a single run can send the count spiking well past it.

What we actually need are the orders our app created or touched, mostly pre-orders. Those are already rows in our database.

So how do you tell Shopify which updates you care about?

You mark them, so the marker shows up in the response you filter on. When a buyer adds one of our pre-orders to their cart, we set an attribute on the cart with the Storefront API's cartAttributesUpdate:

mutation markCart($cartId: ID!) {
  cartAttributesUpdate(
    cartId: $cartId
    attributes: [{ key: "_tracked_by_stoq", value: "true" }]
  ) {
    cart { id }
    userErrors { field message }
  }
}

Shopify copies cart attributes onto the order it creates, as the order's custom attributes, so every order that came through our flow arrives already marked.

With an [[events.subscription]] block in shopify.app.toml. Shopify runs the GraphQL query for each order change, applies the query_filter to the response, and only delivers when it matches:²

[[events.subscription]]
handle = "order-tracked"
topic = "Order"
actions = [ "update" ]
triggers = [ "order.*" ]
uri = "<your EventBridge partner source ARN>"
query = """
query order_tracked($orderId: ID!) {
  order(id: $orderId) {
    id
    displayFinancialStatus
    displayFulfillmentStatus
    lineItems(first: 50) { nodes { id quantity } }
    customAttributes { key value }
  }
}
"""
query_filter = "order.customAttributes.key:'_tracked_by_stoq'"

Shopify evaluates the filter on its side, so an unmarked order never leaves Shopify. Deliveries come through Amazon EventBridge into SQS, and a small translator turns each one back into the shape orders/updated had, so the existing worker barely changed.

Before, every order change reached our workers. After, Shopify runs the query and the filter, and only marked orders get through.

Two rules we learned the hard way:

The filter only sees the response, so whatever you filter on has to be selected in the query.
Subscription queries are capped at 100 complexity points, and nested connection sizes add up fast.

How do you move 30,000 shops over without dropping an update?

In three switches per shop, always in this order:

Shadow: Events deliveries are recorded and compared with the webhook.
Process: Events deliveries are processed for real, alongside the webhook. Duplicates are harmless because the worker is idempotent.
Cut over: the router skips that shop's webhook, and later we delete the webhook subscription altogether.

The router check leans towards processing whenever it's unsure:

def skip_webhook_for_events_cutover?(topic:, shop:)
  return false if events_disabled?
  return false unless shop&.events_enabled?
  return false unless CUTOVER_TOPICS.include?(topic)

  # only skip the webhook once Events is already doing the work
  processing_events_for?(shop, topic)
rescue StandardError
  false # a duplicate is a no-op; a dropped update is unrecoverable
end

Leave a gap between steps 2 and 3. Requests already in flight need time to catch up, and if you flip both at once, an update can slip between the webhook you just stopped and the Events delivery that isn't being processed yet.

What bit us?

The dangerous ones failed silently and looked like success until we compared counts.

A search filter Shopify can't apply matches everything. Our hourly reconciler finds marked orders through Admin API order search. When a shop wasn't set up for that filter, Shopify ignored the term and returned every order, with no error. The canary we use now: search for a value that can't exist, and expect 0.

A query error drops the delivery. If the query touches a field the shop's token can't read, Shopify sends a query_errors payload instead. In shadow we found we were dropping about 80% of order deliveries this way. Now we tolerate partial payloads, and shops missing the scope stay on webhooks.

Did it work?

Order-update jobs fell from about 6 million a day on average to under 500,000, a drop of over 90%, and what's left is mostly orders we actually care about. The volume now scales with our pre-orders, not the merchant's whole order backlog. An hourly reconciler, searching for the same marker, catches the few changes Events has no trigger for yet.

orders/updated per day, 16–30 September. Shaded columns are weekends. ① first shops cut over · ② the rest of the fleet · ③ old webhook subscriptions deleted.

And that covers moving orders/updated to Events. Inventory and product updates are next, with the same pattern. If you're doing something similar, or want to compare notes, say hi on X.

About Events and webhooks, and the Events API reference. ↩︎
Events delivery structure and Filter Events deliveries. ↩︎

Gmail API and Rails: sending emails through ActionMailer

2019-01-03T00:00:00Z

When I was working with my friends on Foxbound, one of the main features we needed for the sales automation tool was to send emails through a user's Gmail account. Getting this to work in Ruby is easy once you manage to find the documentation. However, I wanted to integrate it with ActionMailer, because it's a nice structured way of writing mailers and it lets us leverage built-in functionality like the ActiveJob integration to queue up mail for later.

So that's how I got around to writing a gem to add Gmail HTTP API support for ActionMailer, which led to the creation of google-http-actionmailer.

So how do you send mail through the Gmail HTTP API in Ruby?

gem 'google-api-client'

require 'google/apis/gmail_v1'

mail = Mail.new
# ...

service = Google::Apis::GmailV1::GmailService.new
service.authorization = access_token # You'll get this through your refresh token

message = Google::Apis::GmailV1::Message.new(
  raw: mail.to_s
)

service.send_user_message(
  user_id, # ID of the user or 'me' for current authenticated user
  message
)

In the gem, this code is incorporated as a custom delivery method that gets included into ActionMailer.

What can google-http-actionmailer do?

The gem is a plug-and-play solution for sending mail through the Google HTTP API for Gmail. It's easy to configure.

While working on Foxbound, we also found that we wanted to track the emails we sent and the threads they were in. The message ID and thread ID come back in the response from the Gmail API.

So we added hooks that trigger on your mail object before and after the email is sent. This lets you write callbacks to store details, trigger actions conditionally, and so on.

How do I use google-http-actionmailer?

Set up your authorization as described in the Google API Client (the easiest method is to pass a valid access token, which I describe below), then edit config/application.rb or config/environments/<ENVIRONMENT>.rb and add or change the ActionMailer configuration:

config.action_mailer.delivery_method = :google_http_actionmailer

config.action_mailer.google_http_actionmailer_settings = {
  authorization: ...,
  client_options: {
    application_name: ...,
    application_version: ...,
  },
  request_options: {
    retries: ...,
    header: ...,
  },
  message_options: {
    fields: ...,
    content_type: ...,
  },
  delivery_options: {
    before_send: ...,
    after_send: ...,
  }
}

For client and request options, see the options in the Google API client. For message options, see the send_user_message method in the Gmail service.

Normal ActionMailer usage will now be sent using Google's HTTPS API.

If you go with access tokens for authorization, you'll need to know how to refresh them and how to set the token dynamically at the time of sending, which I describe below.

Refreshing access tokens

This requires the omniauth-google-oauth2 gem. We use our existing access token and refresh token to obtain a new token.

strategy = OmniAuth::Strategies::GoogleOauth2.new(nil, <GOOGLE_CLIENT_ID>, <GOOGLE_CLIENT_SECRET>)
client = strategy.client
token = OAuth2::AccessToken.new client, access_token, { refresh_token: refresh_token }
new_token = token.refresh!
# Store the new token

Dynamically setting the delivery method

Access tokens usually expire, so you may need to set the delivery method dynamically. For that we use an interceptor. Interceptors are a concept in ActionMailer: they receive the message before it's sent, so you can use them to modify messages on the way out. In this case we use an interceptor to set the delivery method with a token we refreshed:

class DynamicSettingsInterceptor
  def self.delivering_email(message)
    token = user.new_token

    message.delivery_method(
      GoogleHttpActionmailer::DeliveryMethod,
      {
        authorization: token
      }
    )

    message
  end
end

register_interceptor ::DynamicSettingsInterceptor

Setting after-send and before-send hooks

Sometimes we want the object returned by the Gmail API, perhaps to store details of the email that was sent. For that we can use delivery options: pass a proc that takes two parameters, mail (the object created by ActionMailer) and message (the object created by the Gmail API), to the after_send and before_send hooks.

config.action_mailer.delivery_method = :google_http_actionmailer

config.action_mailer.google_http_actionmailer_settings = {
  authorization: access_token,
  ...
  delivery_options: {
    after_send: ->(mail, message) {
      ...
    },
    before_send: ->(mail, message) {
      ...
    }
  }
}

And that covers using google-http-actionmailer. If you'd like to look at the code, contribute or make suggestions, head over to GitHub, or say hi on X.

Organize your development processes with Overmind

2018-10-29T00:00:00Z

Rarely can a developer get away with running just a single process to get their entire development environment running.

To start developing our apps we often have to spin up a bunch of processes, for example:

the API server (e.g. rails)
the client app (e.g. webpack)
the background job processor (e.g. sidekiq)
and there could be many others…

We usually run these separately in multiple terminal windows, or run one script that forks the processes, and so on.

One popular way to tame this jumbled mess of processes is a Procfile — a format to specify the types of processes an application provides and the commands to run them. It's a standard for Heroku and other platforms-as-a-service.

A simple Procfile defining a web process that runs rails server and a worker process that runs sidekiq:

web: rails s
worker: bundle exec sidekiq

There are a bunch of tools to run a Procfile, the most famous being foreman by David Dollar, but I'd like to show you how we can take Procfiles to the next level with Overmind.

What is Overmind?

Frustrated with existing Procfile-based process management tools, Sergey Alexandrovich set out to make a tool that solved his problem. As explained on the GitHub project:

The problem with most of those tools is that processes you want to manage start to think they are logging their output into a file, and that can lead to all sorts of problems: severe lagging, losing or breaking colored output. Tools can also add vanity information (unneeded timestamps in logs).

He solved these problems with the project Hivemind. However, that wasn't enough: he wanted processes to be bundled together in their output but still be directly accessible to the developer. He went on to integrate tmux with Hivemind to create Overmind.

So what can Overmind do that other Procfile managers cannot? Here's the list from the GitHub repository:

It starts processes in a tmux session (more on tmux later), so you can easily connect to any process and gain control over it. This is especially useful because it lets us connect to debuggers.
It can restart a single process on the fly — you don't need to restart the whole stack.
It allows a specified process to die without interrupting all of the others.
It uses pty to capture process output — so it won't be clipped or delayed, and it won't break colored output.
It can read environment variables from a file and use them as parameters, so you can configure Overmind behavior globally and/or per directory.

How to set up Overmind

Note: Overmind supports Linux, *BSD and macOS only.

Now that you've heard what Overmind can do for you, let's set it up.

Overmind requires tmux, so install it first:

# on macOS (with Homebrew)
$ brew install tmux

# on Ubuntu
$ apt-get install tmux

On macOS it's easiest to install Overmind with Homebrew:

$ brew install overmind

Otherwise you can download the latest binary or build from source.

Once you're done, start it with:

$ overmind start -f path/to/your/Procfile

tmux

The secret ingredient in Overmind is tmux, a terminal multiplexer. It lets you switch between several programs in one terminal, detach them while they keep running in the background, and reattach them to a different terminal. You don't need to know tmux to use Overmind, but a little knowledge helps.

A few useful commands:

Ctrl + b d — detach from the tmux window once you're inside with overmind connect
Ctrl + b 0 — each process gets a number in the tmux window, which you can use to move between processes

Note: my tmux looks different because I've customised it. You can customise yours by editing your .tmux.conf; tmux by gpakosz is a good place to start.

Debugging made easy again

When we're debugging an issue we usually want to use pry or byebug for live debugging. However, with most Procfile managers or other ways of running processes side by side, we can't reach the debugging console for the process. Overmind lets us connect to any running process in a new window with overmind connect <process name>. In the picture below, the debugger started on the web process, and I used overmind connect web to connect to that process and start debugging.

Debugging made easy

Restarting quickly

Often we want to restart just one of the processes in our Procfile, perhaps the sidekiq worker, and with foreman we have to close it and all our processes. With Overmind, overmind restart <process name> restarts just that process.

Procfiles for everything

Generally we don't have just one stack of processes to run. You might have a separate set to run your Slack bot or to boot your acceptance test server. Since Overmind runs on Procfiles, we can create different sets for each use case, like a Procfile.slack that boots the event listener and ngrok, or a Procfile.acceptance that boots your acceptance server and runs the database setup.

# Procfile.slack
listener: bundle exec rake slack:listen_for_events
localtunnel: ngrok http 3000

# Procfile.dev
web: rails s
worker: bundle exec sidekiq

# Procfile.acceptance
client: rake acceptance:client
server: rake acceptance:server

If you run multiple Procfiles simultaneously from the same path, you'll run into this error:

overmind: it looks like Overmind is already running. If it's not, remove path/to/project/.overmind.sock and try again

You can fix this by giving each set its own socket: overmind start -f Procfile.dev -s ./dev.sock. Once you start Overmind with a socket, run all your commands with the same socket.

$ overmind connect -s path/to/socket web
$ overmind restart -s path/to/socket sidekiq
$ overmind kill -s path/to/socket

Thanks for reading! If you have suggestions or anything else to share, say hi on X.

OAuth redirects (and others) in embedded Shopify apps

2018-01-15T00:00:00Z

2026 note: this describes the 2018 embedded app SDK. Embedded apps now use App Bridge, where window.open(url, "_top") navigates the top frame. The lesson about reading your gems' source still stands.

Redirecting out of your embedded Shopify app isn't quite straightforward. I'd integrated Facebook AdInsights data into my app but was unable to get the OAuth request to work within the embedded iframe, as it blocks the request. I'd taken to using a workaround: opening the authentication page in another tab that wasn't embedded. This was pretty clearly bad UX, but I couldn't figure my way around it.

That was until I went through the code of the very useful shopify_app gem that I'd been using this whole time and found the fullpage_redirect_to method. On further inspection I found in the Shopify documentation that there was a way to get your request out of the iframe.

The great escape

Since your app is loaded in an iframe, you can't use the usual redirect_to 'auth/facebook', assuming you're using Facebook OmniAuth.

You have to instead return a page with:

<script type='text/javascript'>
  // If the current window is the 'parent', change the URL by setting location.href
  if (window.top == window.self) {
    window.top.location.href = "/auth/facebook";

  // If the current window is the 'child', change the parent's URL with postMessage
  } else {
    message = JSON.stringify({
      message: "Shopify.API.remoteRedirect",
      data: { location: window.location.origin + "/auth/facebook" }
    });
    window.parent.postMessage(message, "https://myshopname.myshopify.com");
  }
</script>

On the Rails

shopify_app implements this in a reusable way. The fullpage_redirect_to method renders an HTML page if we're in an embedded app. Otherwise it does a normal redirect.

def fullpage_redirect_to(url)
  if ShopifyApp.configuration.embedded_app?
    render 'shopify_app/shared/redirect', locals: { url: url, current_shopify_domain: current_shopify_domain }
  else
    redirect_to url
  end
end

The HTML page contains a <div> with the parameters for our redirect as data attributes.

...
<body>
  <%=
  content_tag(:div, nil,
    id: 'redirection-target',
    data: {
      target: {
        myshopifyUrl: "https://#{current_shopify_domain}",
        url: url,
      },
    },
  )
  %>
</body>
...

The JS function picks up these parameters and triggers the redirection script.

document.addEventListener("DOMContentLoaded", function() {
  var redirectTargetElement = document.getElementById("redirection-target");
  var targetInfo = JSON.parse(redirectTargetElement.dataset.target)

  if (window.top == window.self) {
    // If the current window is the 'parent', change the URL by setting location.href
    window.top.location.href = targetInfo.url;
  } else {
    // If the current window is the 'child', change the parent's URL with postMessage
    normalizedLink = document.createElement('a');
    normalizedLink.href = targetInfo.url;

    data = JSON.stringify({
      message: 'Shopify.API.remoteRedirect',
      data: { location: normalizedLink.href }
    });
    window.parent.postMessage(data, targetInfo.myshopifyUrl);
  }
});

Conclusion

It's always a good idea to read through the code of the gems you use if you're having trouble, especially open source ones. Documentation is generally sparse because the maintainers might not have the time.