Webhooks & Background Jobs

What a webhook is

Normally your app asks Shopify for things. A webhook is the reverse: Shopify calls your server to say something happened.

It is just an HTTP POST to a route in your app, with the event data as JSON.

Registering one

You declare which events you want in the TOML:

[webhooks]
api_version = "2026-01"

  [[webhooks.subscriptions]]
  topics = [ "app/uninstalled" ]
  uri = "/webhooks/app/uninstalled"

  [[webhooks.subscriptions]]
  topics = [ "products/update", "products/delete" ]
  uri = "/webhooks/products"

Topic = the event name. uri = the route in your app that receives it. Several topics can share one route.

The handler

import { authenticate } from "../shopify.server";

export const action = async ({ request }) => {
  const { shop, topic, payload } = await authenticate.webhook(request);

  if (topic === "PRODUCTS_UPDATE") {
    // react to the change
  }

  return new Response();     // 200 = "received"
};
// no default export — this is not a page

Three things to notice:

• The filename does not start with app., so it is not behind the merchant login. Shopify has no login — it is a server calling a server.
• authenticate.webhook verifies the request really came from Shopify by checking its signature. Never skip this, or anyone could POST fake events at you.
• No default export, so it returns data rather than a page.

The golden rule: answer fast

Shopify waits only a few seconds for your 200 response. Take longer and it counts as a failure — and Shopify retries, repeatedly, over the next couple of days.

The pattern: record what happened, respond immediately, do the work afterwards.

export const action = async ({ request }) => {
  const { shop, topic, payload } = await authenticate.webhook(request);

  // fast: just write a row saying "this needs doing"
  await db.pendingTask.create({
    data: { shop, topic, productGid: payload.admin_graphql_api_id },
  });

  return new Response();        // answer in milliseconds
};

A background job then picks the row up and does the slow part. Small updates that take a few milliseconds are fine to do inline — it is the slow work that needs moving.

The same event can arrive twice

Shopify guarantees at least one delivery, not exactly one. Duplicates happen, and events can arrive out of order.

So handlers must be safe to run twice. The technical word is idempotent: running it again changes nothing extra.

// Fragile — two deliveries, two rows
await db.log.create({ data: { productGid } });

// Safe — two deliveries, one row
await db.log.upsert({
  where:  { productGid },
  update: { updatedAt: new Date() },
  create: { productGid, shop },
});

Prefer upsert and "set to this value" over "add one to this counter". Deletes should tolerate the row already being gone — which is why deleteMany is easier than delete.

Testing without waiting for real events

shopify app webhook trigger

It asks which topic to send and fires a realistic fake payload at your app. You no longer have to uninstall your app to test the uninstall handler, or place an order to test an order handler.

Add a log line at the top of every handler while developing:

console.log(`Received ${topic} for ${shop}`);

Then shopify app logs shows deliveries as they arrive, including in production.

Background jobs

Webhooks react to events. Sometimes you need work that runs on a schedule instead: nightly cleanup, syncing data, retrying failures.

A small scheduler in your server process is usually enough:

import cron from "node-cron";
import db from "../../app/db.server.js";
import { unauthenticated } from "../../app/shopify.server.js";

export function startSyncJob() {
  cron.schedule("*/5 * * * *", runPending);   // every 5 minutes
}

import { startSyncJob } from "./server/jobs/syncJob.js";

startSyncJob();                // once, at startup
app.listen(PORT);

const { admin } = await unauthenticated.admin(shop);

Writing a job that behaves

1. Stop it overlapping itself

If a run takes longer than the interval, the next tick starts while the first is still going.

let isRunning = false;

async function runPending() {
  if (isRunning) return;        // skip this tick
  isRunning = true;
  try {
    // ... the work
  } finally {
    isRunning = false;            // always release, even on error
  }
}

2. Let one shop's failure not stop the rest

for (const row of pending) {
  try {
    await processShop(row.shop);
    await db.task.update({
      where: { id: row.id },
      data:  { done: true, lastRunAt: new Date(), lastError: null },
    });
  } catch (err) {
    // record the reason, leave it pending, move on
    await db.task.update({
      where: { id: row.id },
      data:  { lastRunAt: new Date(), lastError: err.message },
    });
  }
}

Storing lastError on the row is the single most useful debugging decision you can make. Without it, a job that quietly fails for one shop is invisible.

3. Only pick up work that needs doing

Give each row a flag saying whether it has been handled:

const pending = await db.task.findMany({ where: { done: false } });

Mark it done on success, and leave it alone on failure so the next tick retries. The job then does nothing at all when there is nothing to do — which is what you want running every five minutes forever.

4. Go one at a time

Process shops sequentially, not with Promise.all. Batch large updates, and retry when the API throttles you (Note 06). A background job is rarely urgent — being gentle costs you nothing.

Two things that surprise people

if (process.env.ENABLE_JOBS === "true") startSyncJob();

Choosing between them

The last one is worth planning for. Webhooks can be missed — your server may be down during a deploy. A periodic job that re-checks and corrects drift makes the whole system self-healing.

Common problems

Checklist

• Handlers call authenticate.webhook first — always.
• Webhook files are not named app.* and have no default export.
• Handlers return 200 in milliseconds; slow work is handed to a job.
• Handlers are safe to run twice (upsert, not create).
• Jobs have an overlap guard released in finally.
• Jobs process shops one at a time, and one failure does not stop the rest.
• Failures record lastError and lastRunAt on the row.
• You know whether you run one instance or several.

Cheat sheet

# register (then deploy!)
[[webhooks.subscriptions]]
topics = [ "products/update" ]
uri = "/webhooks/products"

# handler
const { shop, topic, payload } = await authenticate.webhook(request);
return new Response();           # fast 200

# rules
verify first              never trust an unverified payload
answer in milliseconds    slow work → record it, do it later
be idempotent             upsert, not create — duplicates WILL arrive

# jobs
cron.schedule("*/5 * * * *", run)     started once in server.js
unauthenticated.admin(shop)           no request = no session
isRunning guard, released in finally
find where done: false, mark done on success
record lastError on failure, leave pending to retry

# test
shopify app webhook trigger
shopify app logs