shopify-webhook-topic
/shopify-webhook-topic
Dodaje lub zmienia obsługę webhooka Shopify w Order Hub, na przykład zamówień, klientów, zwrotów lub produktów, i sposób zapisu jego danych.
- Autor
- fsemilia ↗
- Repozytorium
- order-hub ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 12.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Dodaje lub zmienia obsługę webhooka Shopify w Order Hub, na przykład zamówień, klientów, zwrotów lub produktów, i sposób zapisu jego danych.
Wyzwalacze z opisu
Oryginalny opis (EN)
Add or change handling of a Shopify webhook topic in Order Hub (orders/*, customers/*, refunds/*, products/*, compliance topics). Use when the user asks to "handle a new webhook", "subscribe to X", "process refunds/create", or changes how a webhook payload is stored.
Jak działa
- Steps
- Response codes (do not change without an ADR)
Podgląd SKILL.md
---
name: shopify-webhook-topic
description: Add or change handling of a Shopify webhook topic in Order Hub (orders/*, customers/*, refunds/*, products/*, compliance topics). Use when the user asks to "handle a new webhook", "subscribe to X", "process refunds/create", or changes how a webhook payload is stored.
---
# Adding a Shopify webhook topic
The pipeline lives in `lib/shopify/webhooks.ts` (`handleShopifyWebhook`). Never bypass it: it owns
HMAC verification, the idempotency log and the transaction. A new topic is a handler, not a new route.
## Steps
1. **Check the payload shape** before writing code. Use the Shopify Dev MCP (`shopify-dev-mcp`
server in `.mcp.json`) to read the webhook reference for the topic and the API version pinned in
`shopify.app.toml` (`[webhooks] api_version`). Do not guess field names.
2. **Schema** — add a Zod schema in `lib/shopify/schemas.ts`:
- IDs: `shopifyId` helper (number|string → string).
- Money: `money` helper (decimal _string_). Never `z.number()` for prices.
- Dates: `isoDate` helper.
- Only the fields we use; unknown fields are stripped.
3. **Domain function** in `lib/shopify/ingest.ts` taking `(tx: Prisma.TransactionClient, parsed)`:
- Must be idempotent (upsert by `shopifyId`, never blind `create`).
- Respect the stale guard pattern (`shopifyUpdatedAt`) for resources that have `updated_at`.
- If it changes orders, call `recomputeCustomerAggregates(tx, customerId)` in the same tx.
- Never resurrect PII of a customer with `redactedAt` set.
4. **Register** the topic in `HANDLERS` (`lib/shopify/webhooks.ts`).
5. **Subscribe** in `shopify.app.toml` under `[[webhooks.subscriptions]]`.
6. **Fixture** in `tests/fixtures/<topic>.json` with realistic, _13-digit_ IDs (JSON.parse loses
precision above 2^53 — Shopify IDs fit, invented 18-digit ones do not).
7. **Tests** in `tests/integration/shopify-webhook.test.ts` using the `deliver()` helper. Minimum:
happy path, duplicate delivery (same webhook id), invalid payload → 422 with nothing written,
and out-of-order delivery if the resource has `updated_at`.
8. Run `npm run test:integration` (needs `npm run db:test:start`) and `npm run check`.
9. Manual check: `npm run webhook:send -- --topic <topic> --fixture tests/fixtures/<topic>.json`.
## Response codes (do not change without an ADR)
| Situation | Status | Why |
| -------------------- | ---------------------- | ------------------------------- |
| Bad HMAC | 401 | not from Shopify |
| Duplicate webhook id | 200 `{duplicate:true}` | stop Shopify retries |
| Invalid payload | 422, rolled back | logged; fixable then replayable |
| Unknown topic | 200 `{ignored}` | avoid retry storms |
| Anything else | throw → 500 | Shopify retries with backoff |
Wersje
W bazie nie ma innych skilli o nazwie shopify-webhook-topic.
Migawka bazy z 13.11.2026 · wersja paczki ef776d121905 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100shopify-webhooks-events
Rejestruje i obsługuje webhooki Shopify, w tym obowiązkowe tematy zgodności z GDPR wymagane przy zgłoszeniu do App Store, oraz zdarzenia zamówień i produktów. - 100shopify-webhooks
Odbiera i weryfikuje webhooki Shopify: obsługa zdarzeń sklepu, takich jak orders/create, products/update i customers/create, oraz diagnozowanie weryfikacji podpisu. - 100shopify-orders
Zarządza zamówieniami Shopify: cykl życia zamówienia, model FulfillmentOrder, zwroty i refundacje, zamówienia robocze, edycja zamówień, transakcje, metafields i analiza ryzyka. - 100shopify-core-workflow-b
Zarządza zamówieniami, klientami i realizacją zamówień Shopify przez GraphQL Admin API: zapytania o zamówienia, fulfillment i integracje zarządzania zamówieniami. - 96shopify
Pomaga budować aplikacje, motywy i rozszerzenia dla platformy Shopify na prośbę użytkownika. - 100shopify
Pracuje z zasobami Shopify przez Admin GraphQL: odczyt i zmiany produktów, zamówień, klientów i stanów, w kilku sklepach naraz.