# Add Order Webhooks to a Shopify App

Yes. An agent subscribes a Shopify app to orders/paid in its TOML, adds a route that verifies, deduplicates and stores each event, runs the checks and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-order-webhooks/shopify-app/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the app already receives webhooks before it adds one. In a Shopify app like Shopify/shopify-app-template-react-router, `shopify.app.toml` sets `scopes = "write_products"` and a `[webhooks]` block on API version `2026-10` with two app-specific subscriptions, `app/uninstalled` at `/webhooks/app/uninstalled` and `app/scopes_update` at `/webhooks/app/scopes_update`, the three compliance topics commented out, and an `[events]` block that subscribes to `Product` updates filtered to price changes with a GraphQL query attached. `app/routes.ts` uses `flatRoutes()`, so a file named `webhooks.products.update.tsx` is the `/webhooks/products/update` route; that handler calls `authenticate.webhook(request)` from `app/shopify.server.ts`, logs the topic and payload and returns `200`, while `webhooks.app.uninstalled.tsx` deletes the shop's sessions through Prisma. `shopify.server.ts` builds the app with `ApiVersion.October26`, `PrismaSessionStorage` and `expiringOfflineAccessTokens: true`; `prisma/schema.prisma` is SQLite with a single `Session` model and one migration. `.github/workflows/ci.yml` runs `tsc --noEmit`, ESLint, `prisma generate` and `prisma validate` and `npm run build` across Node 22 and 24 and three package managers. The README says to declare webhooks in the TOML rather than in `afterAuth`, and that events triggered from the CLI arrive with `admin` set to `undefined`.

The change follows that pattern. The agent adds `read_orders` to `scopes`, since order topics need it, and a `[[webhooks.subscriptions]]` entry for `orders/paid` at `/webhooks/orders/paid`, with a comment naming the handler file the way the existing entries do. The handler, `app/routes/webhooks.orders.paid.tsx`, calls `authenticate.webhook`, which verifies the HMAC and returns `shop`, `topic`, `payload` and `webhookId`. Shopify retries a delivery that does not get a `2xx` quickly and can deliver the same event twice, so the handler writes the `webhookId` first: a new `WebhookEvent` model in `schema.prisma` with the id as primary key, the shop, the topic and a received-at time, created inside a `try` that treats a unique-constraint failure as a duplicate and returns `200` without doing the work again. For a first delivery it stores what the payload carries that a merchant-facing feature needs: the order's id, name, total price with its currency, the customer email when present, and the financial status, in an `Order` model keyed by shop and order id, and answers `200`. A `prisma migrate dev` run produces the migration directory beside the existing `20240530213853_create_session_table`.

Two things in this template shape the work and are spelled out rather than worked around. Raising the scopes means every installed shop must grant `read_orders` again, which the existing `app/scopes_update` handler already receives; the pull request says that `shopify app deploy` syncs the TOML and that merchants see the new permission on their next visit. And order payloads carry customer fields that Shopify treats as protected customer data, so a public app must request that access in the Partner Dashboard before the webhook fires with those fields; the handler stores the email only when the payload includes it, and the pull request names the setting.

The agent checks the change the way CI does: `npm run typecheck`, which runs `react-router typegen` and `tsc --noEmit` so the new route's types are generated, `npm run lint`, `npx prisma validate` and `npm run build`. It cannot run `shopify app deploy` or `shopify app webhook trigger` without the app's credentials, so it writes a small unit test around the handler's dedupe branch with Node's built-in test runner, since the template ships no test framework, using the Prisma client against a temporary SQLite file, runs it, and leaves the CLI trigger command in the pull request for the reviewer.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add an orders/paid webhook to this Shopify app. Read shopify.app.toml, app/shopify.server.ts, app/routes.ts, every file under app/routes/webhooks.*, prisma/schema.prisma, the CI workflow and the README's webhook notes first. Add read_orders to the access scopes and an app-specific subscription for orders/paid in the TOML with a comment naming its handler, following the existing entries. Write the handler route using authenticate.webhook. Make it idempotent: add a Prisma model keyed by the webhook id, insert it before any work and treat a duplicate key as an already-handled delivery that still answers 200. Store the order's id, name, total price with currency, financial status and customer email when present in an Order model keyed by shop and order id, and create the migration with prisma migrate dev. Explain in the pull request what the scope change means for installed shops and which Partner Dashboard access order payloads need. Run npm run typecheck, npm run lint, npx prisma validate and npm run build, add a test for the dedupe path against a temporary SQLite database, and open a pull request with the results and the CLI command a reviewer can use to trigger the event.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request with the TOML changes, `app/routes/webhooks.orders.paid.tsx`, the two Prisma models and their migration directory, and a test for the duplicate-delivery branch. Its description quotes the typecheck, lint, Prisma validate and build output from the run, states the scope change and the protected-data requirement, and gives the `shopify app webhook trigger` command for `orders/paid` pointed at the new route.

A reviewer checks that the subscription's `uri` matches the route file name that `flatRoutes` produces, that the handler answers `200` before any slow work so Shopify does not retry, and that the `Order` fields are the ones a feature will read, since every later field is another migration. After merging, `shopify app deploy` registers the subscription and the next paid order reaches the route.

## Run it on every Linear issue labelled webhooks

In the console, add an automation on the Project with a `linear` trigger on `linear.issue.labeled` and the label `webhooks`, with the prompt above. When a person on the team labels an issue that names a topic such as `orders/paid` or `fulfillments/create`, the run starts with the issue as its context, makes the change in the Project's repository and opens a pull request on its own branch linked to the issue. A label applied by an app integration never fires it.

From your own tooling, send this body to `POST /o/{org}/sessions` with the issue text appended to the prompt and a `request_id` that is a UUID v5 of the issue id, so a retried webhook from your side returns the run already started.

## Why run it on Rush?

The handler is a few dozen lines; the care is in the parts around it: the scope that the subscription needs, the retry behaviour that makes an idempotency table necessary, the migration, and the type generation that CI runs. The agent reads the template's own notes and files, runs the same checks CI will, and keeps every command and its output in the run's record, so the pull request shows what passed rather than asserting it.

The same run fits any Shopify app built on the React Router or Remix templates: a Postgres session store instead of SQLite, a second topic such as `refunds/create`, or an app that forwards each event to a queue instead of storing it. Each gets a handler shaped by its own `shopify.server.ts` and a migration in its own Prisma history.

## Frequently asked questions

### Why declare the subscription in the TOML instead of registering it in afterAuth?

The template's README says so: app-specific subscriptions in `shopify.app.toml` are synced on every `shopify app deploy`, while `afterAuth` runs only on install or when a token expires, so shop-specific subscriptions registered there go stale. The run follows the file's existing entries.

### Why does the handler store the webhook id first?

Shopify retries any delivery that does not get a `2xx` in time and can send the same event more than once. Inserting the id with a unique constraint before doing any work means a second delivery hits the constraint and returns `200` without creating a second order row.

### What changes for merchants who already installed the app?

Adding `read_orders` changes the requested scopes, so each shop is asked to approve the new permission on its next visit to the app, and the existing `app/scopes_update` handler receives the change. The pull request says this so the team can time the deploy.

### Can the run test the webhook end to end?

Not without the app's Partner credentials, which the sandbox does not have. It runs the same checks as CI plus a test of the dedupe branch, and the pull request gives the `shopify app webhook trigger` command; an event sent that way arrives with `admin` set to `undefined`, as the README notes, which the handler does not need.

## More Shopify app jobs

- [Add Retry Logic for Throttled Shopify Admin API Calls](https://getrush.ai/run/add-retry-logic/shopify-app/)
- [Add a Theme App Extension to a Shopify App](https://getrush.ai/run/add-theme-app-extension/shopify-app/)
- [Move a Shopify App's Session Storage From SQLite to Postgres](https://getrush.ai/run/migrate-sqlite-to-postgres/shopify-app/)

## More jobs like this: Turn a Linear label into a PR

- [Add Output Channel Logging to a VS Code Extension](https://getrush.ai/run/add-output-channel-logging/vscode-extension/)
- [Set a Document Title per Page in a SolidJS App](https://getrush.ai/run/add-page-titles/solidjs/)
- [Add Cursor Pagination to a FastAPI Endpoint from a Linear Issue](https://getrush.ai/run/add-pagination/fastapi/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
