Outbound webhooks and Shopify topics
Inbound Shopify topics
POST /webhooks receives Shopify webhook payloads and authenticates them with HMAC signature verification before any topic side effect. The shop header is not trusted for authorization; the canonical order GID is resolved through persisted merge-job ownership and must match the server-owned tenant.
Compliance and account-state topics execute synchronously, so a 200 response means their effects are complete. Order, fulfillment, and refund topics are durably enqueued to the merge queue before the Worker returns 200. Completed duplicate delivery IDs return 200 without repeating work.
The three compliance topics verify the HMAC against the unchanged raw bytes before JSON parsing. A supplied
X-Shopify-Webhook-Id is the retry-deduplication key. Without it, customers/data_request derives a deterministic key from the topic and a SHA-256 hash of the raw body; headerless customers/redact and shop/redact requests get a fresh per-request key and rely on idempotent handlers.
Webhook subscriptions are declared in shopify.app.toml for orders/create, orders/updated, refunds/create, fulfillments/create, app/uninstalled, app_subscriptions/update, shop/update, and the three compliance topics, all pointing at /webhooks.
Outbound events
Pro merchants can subscribe to these events. Each subscription receives a signedPOST to the registered URL, and each delivery carries the X-OrderMerge-Signature, X-OrderMerge-Event, and X-OrderMerge-Shop headers described in the API overview.
The event payload carries
version, event, shop, jobId, primaryOrderId, secondaryOrderIds, status, shippingRefundAmount, and occurredAt.
Subscription endpoints must use HTTPS and a public destination; registration and delivery reject loopback, private, link-local, reserved, and documentation IP literals, single-label hosts, and local or internal DNS suffixes.
Pcnaid Documentation › Shopify Ecosystem › Order Merge Pro › Developer