Shopify's webhook delivery timeout is 5 seconds. After 19 consecutive failures, Shopify removes the subscription entirely. Your app silently stops working for every affected merchant.
Synchronous webhook handlers cause this. Async architecture prevents it.
Here are the five patterns every Shopify developer needs in production.
- The 50ms Rule: What Belongs in the Webhook Handler Everything in your webhook handler that isn't HMAC validation and queue enqueue is a liability.
js// ✅ Async webhook handler — returns 200 in under 50ms
app.post('/webhooks', express.raw({ type: '*/*' }), async (req, res) => {
const hmac = req.headers['x-shopify-hmac-sha256'];
const topic = req.headers['x-shopify-topic'];
const shop = req.headers['x-shopify-shop-domain'];
const webhook = req.headers['x-shopify-webhook-id'];
if (!verifyShopifyHmac(req.body, hmac)) {
return res.status(401).send('Unauthorized');
}
await ingestionQueue.add('webhook', {
topic, shop, webhookId: webhook,
payload: JSON.parse(req.body)
});
res.status(200).send('OK'); // Return before any processing
});
Everything else — database writes, API calls, notifications — goes into a background worker.
- Three-Tier Queue Topology One queue for everything means a slow fulfillment API backs up your ingestion layer. Separate by concern:
js// Tier 1: Ingestion — validate and route only
const ingestionQueue = new Queue('shopify:ingestion', { connection });
// Tier 2: Domain queues — isolated scaling + retry policies
const ordersQueue = new Queue('shopify:orders', { connection });
const inventoryQueue = new Queue('shopify:inventory', { connection });
const fulfillmentQueue = new Queue('shopify:fulfillment', { connection });
// Tier 3: Notifications — lower priority, higher tolerance
const notificationQueue = new Queue('shopify:notifications', { connection });
Each domain queue gets its own retry policy. Order processing: 5 retries, 2-minute exponential backoff. Notifications: 3 retries, 30-second delay. Mixing them forces a single policy compromise on everything.
- Saga Pattern for Multi-Step Fulfillment Any workflow spanning more than one external API call needs compensating transactions. Without them, a mid-workflow failure leaves your system partially applied with no automatic recovery path.
js// Step 1: Reserve inventory → emit inventory.reserved or inventory.insufficient
eventBus.subscribe('inventory-service', 'w1', async (event) => {
if (event.type !== 'order.confirmed') return;
try {
await reserveInventory(event.shop, event.payload.lineItems);
await eventBus.emit('inventory.reserved', event.shop, event.payload);
} catch (err) {
await releasePartialReservations(event.shop, event.payload.orderId);
await eventBus.emit('inventory.insufficient', event.shop, event.payload);
}
});
// Step 2: Submit to 3PL → trigger only after inventory confirmed
eventBus.subscribe('fulfillment-service', 'w1', async (event) => {
if (event.type !== 'inventory.reserved') return;
try {
const id = await submit3PLOrder(event.payload);
await eventBus.emit('fulfillment.submitted', event.shop, { ...event.payload, id });
} catch (err) {
await releaseReservation(event.shop, event.payload.orderId); // Compensate
await eventBus.emit('fulfillment.failed', event.shop, event.payload);
}
});
Each step is an independent async worker. A 3PL outage pauses fulfillment without touching inventory reservation or order status updates for orders already past that step.
- Idempotency Keys: The Minimum Viable Duplicate Guard Shopify guarantees at-least-once delivery. Your workers will execute the same payload more than once.
jsasync function processOrder(shop, orderId, payload) {
const key = `processed:order:${shop}:${orderId}`;
const isNew = await redis.set(key, '1', { NX: true, EX: 86400 });
if (!isNew) return { status: 'duplicate' }; // Already done
try {
await updateCRM(shop, payload.customer);
await submitFulfillment(shop, payload);
await sendConfirmation(shop, payload.email);
return { status: 'processed' };
} catch (err) {
await redis.del(key); // Allow retry
throw err;
}
}
SET NX is atomic. Two workers racing on the same key cannot both proceed. Deleting the key on failure ensures retries work correctly.
- Sharded Scheduled Jobs — Prevent the Thundering Herd A nightly reconciliation firing for 10,000 shops simultaneously at 2am UTC saturates your database and API rate limits in seconds.
js// Hash shop ID into time-staggered buckets
function getScheduleMinute(shopId) {
return Number(BigInt(shopId) % BigInt(60)); // 0–59 minutes past the hour
}
// Shop A fires at 2:00am, Shop B at 2:03am, Shop C at 2:47am...
await schedulerQueue.add(
`reconcile:${shop}`,
{ type: 'reconcile', shop },
{ repeat: { pattern: `0 ${getScheduleMinute(shopId)} 2 * *` } }
);
Distributes 10,000 jobs across a 60-minute window. No thundering herd. No database connection pool saturation at 2:00:00.
The Async Pattern Reference
| Pattern | Trigger | Shopify Use Case | Key Concern |
|---|---|---|---|
| Job Queue | Webhook / API event | Order sync, inventory update | Retry + DLQ |
| Event Bus | Domain event | CRM, ERP, analytics fan-out | Consumer isolation |
| Saga | Multi-step transaction | Order fulfillment workflow | Compensating transactions |
| Scheduled Jobs | Time-based | Billing, reports, reconciliation | Thundering herd prevention |
| Deferred Loading | Page request | Hydrogen reviews, inventory | Streaming non-critical data |
Full guide with Redis Streams consumer group implementation, BullMQ three-tier topology, and Hydrogen defer() patterns: https://kolachitech.com/async-shopify-architecture