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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
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
More jobs like this: Turn a Linear label into a PR
- Add Output Channel Logging to a VS Code Extension (VS Code Extension)
- Set a Document Title per Page in a SolidJS App (SolidJS)
- Add Cursor Pagination to a FastAPI Endpoint from a Linear Issue (FastAPI)