Shopify Festive Real-Time Notifications Demo

A developer tutorial application demonstrating how to integrate Shopify webhooks, the Hookdeck Event Gateway, and Ably to display real-time purchase notifications in a Shopify online store with festive animations.

What This Demonstrates

This is an example/tutorial app that shows developers how to:

• Receive Shopify order webhooks reliably through the Hookdeck Event Gateway
• Process webhook events in a Remix-based Shopify app
• Forward events to Ably for real-time pub/sub messaging
• Display live notifications in a Shopify storefront using theme app extensions
• Create interactive UI elements with holiday-themed animations

Note: This is a demonstration app for learning purposes, not a production-ready application for merchants to install.

Architecture Overview

The complete data flow works as follows:

1. Order Created in Shopify
   ↓
2. Shopify triggers orders/create webhook
   ↓
3. Event Gateway receives and queues the webhook at the Source
   ↓
4. Event Gateway delivers webhook to app webhook handler
   (app/routes/webhooks.orders.create.tsx)
   ↓
5. App processes event and publishes to Event Gateway queue
   (app/helpers/webhooks.ts)
   ↓
6. Event Gateway queues and forwards event to Ably via REST API
   ↓
7. Ably broadcasts to all connected clients
   ↓
8. Storefront receives event via Ably Realtime
   (extensions/live-notifications/assets/notifications.js)
   ↓
9. Notification displayed with snowflake animation
   (extensions/live-notifications/blocks/notifications.liquid)

Key Components

Shopify App vs Extension

This project contains both a Shopify app and a theme app extension:

• Shopify App: The backend Remix application that handles webhooks, manages data, and provides an admin interface. It runs on a server and integrates with Shopify's Admin API.
• Theme App Extension: Frontend components that appear in the merchant's online store. Extensions add blocks, sections, or functionality directly to the storefront without modifying theme code.

Backend (Remix App)

• app/routes/webhooks.orders.create.tsx - Webhook endpoint that receives order creation events from Shopify via the Event Gateway
• app/helpers/webhooks.ts - Helper functions for managing webhooks, including:
  • Publishing events to the Event Gateway queue
  • Managing webhook subscriptions via Shopify Admin GraphQL API
  • Note: Connection setup should be handled by a setup script (see Setup Instructions)

Storefront Extension

• extensions/live-notifications/blocks/notifications.liquid - Theme app extension block with festive holiday lights and snowfall animations
• extensions/live-notifications/assets/notifications.js - Client-side JavaScript that:
  • Connects to Ably Realtime
  • Subscribes to notification events
  • Creates snowflake animations
  • Handles interactive elements (clickable lights and snowflakes)
• extensions/live-notifications/src/notifications.scss - Source SCSS styles (compiled to notifications.css)
• extensions/live-notifications/assets/notifications.css - Compiled CSS (generated from SCSS, not manually edited)

Configuration

• shopify.app.toml - Shopify app configuration including:
  • Webhook subscriptions for orders/create
  • Required OAuth scopes (read_products, read_orders)
  • App authentication settings
• package.json - Dependencies including:
  • @shopify/shopify-app-remix - Shopify app framework
  • Ably client library (loaded via CDN in storefront)
  • Note: The @hookdeck/sdk dependency is deprecated and should be removed

Prerequisites

Before setting up this app, you'll need:

1. Node.js (v18.20+, v20.10+, or v21.0.0+)
2. Shopify Partner Account - Create one here
3. Shopify Development Store - Create from your Partner Dashboard
4. Hookdeck Account - Sign up at hookdeck.com for the Event Gateway
5. Hookdeck CLI - Install globally with npm install -g @hookdeck/cli
6. Ably Account - Sign up at ably.com

Environment Variables

Create a .env file in the root directory with the following variables:

# Shopify App Credentials
SHOPIFY_API_KEY=your_shopify_api_key
SHOPIFY_API_SECRET=your_shopify_api_secret

# Hookdeck Configuration
HOOKDECK_API_KEY=your_hookdeck_api_key

# Ably Configuration
ABLY_API_KEY=your_ably_api_key

# Database
DATABASE_URL=file:./dev.sqlite

Getting Your API Keys

Hookdeck API Key:

1. Log in to your Hookdeck Dashboard
2. Navigate to Settings → API Keys
3. Create or copy your API key

Ably API Key:

1. Log in to your Ably Dashboard
2. Navigate to your app → API Keys
3. Create a new key or use the default root key
4. Copy the full API key (format: appId.keyId:keySecret)

Shopify Credentials:

• Created automatically when you run npm run dev for the first time
• Or manually create an app in your Partner Dashboard

Setup Instructions

1. Clone and Install

git clone https://github.com/hookdeck/shopify-festive-notifications.git
cd shopify-festive-notifications
npm install

2. Install and Configure Hookdeck CLI

The Hookdeck CLI is required for this demo application to receive webhooks locally and will be used by the setup script.

1. Install Hookdeck CLI globally:

   npm install -g @hookdeck/cli

2. Login to Hookdeck:

   hookdeck login

   This authenticates the CLI with your Hookdeck account.

3. Configure Shopify App

npm run dev

This will:

• Create a tunnel for local development (using Cloudflare)
• Prompt you to create/select a Shopify app
• Install the app on your development store
• Start the development server

Note on Tunneling:

• The Cloudflare tunnel created by npm run dev is required for Shopify to communicate with your local app (OAuth, app embeds, admin interface)
• The Hookdeck CLI is used to receive webhooks locally and provides better debugging capabilities
• Both run simultaneously: Cloudflare tunnel for the app, Hookdeck CLI for webhooks

Benefits of Hookdeck CLI for webhooks:

• Real-time webhook inspection and debugging
• Replay webhooks during development
• Test different payloads easily
• View webhook history and errors
• No need to trigger real Shopify events repeatedly

4. Start Hookdeck CLI for Local Webhook Development

Start the Hookdeck CLI to forward webhooks to your local server:

hookdeck listen 3000 shopify-webhooks

This creates a webhook URL that forwards to localhost:3000. Keep this terminal running.

Note: The setup script (to be created) will use the Hookdeck CLI to create Event Gateway connections.

5. Configure Event Gateway Connections

Important: Event Gateway connections should be set up statically using a setup script, not dynamically created during app install/uninstall (as Shopify app install/uninstall callbacks can be unreliable).

Create connections in the Event Gateway for each shop:

• Source: Receives webhooks from Shopify
  • Name: {shopId}_order-created
  • URL: Will be the webhook endpoint from Shopify
• Destination: Forwards to Ably REST API
  • Name: {shopId}_ably
  • URL: https://rest.ably.io/channels/{shopId}/messages
  • Auth Method: Bearer token with your Ably API key

TODO: Create a setup script (using Hookdeck CLI) to automate Event Gateway connection creation.

6. Enable the Theme Extension

1. Go to your Shopify admin → Online Store → Themes
2. Click "Customize" on your active theme
3. Navigate to any page in the theme editor
4. Click "Add section" or "Add block"
5. Look for "Festive Notifications" under App blocks
6. Add it to your theme (typically in the theme layout or header)
7. Save and publish

7. Update Ably API Key in Extension

Edit extensions/live-notifications/assets/notifications.js and replace the hardcoded API key on line 45 with your Ably API key:

const ably = new Ably.Realtime("YOUR_ABLY_API_KEY");

Note: In production, this should be handled more securely, potentially using token authentication.

8. Test the Integration

TODO: Add detailed testing instructions including:

• Step-by-step guide to creating a test order
• How to verify webhook delivery in app logs (with expected log output)
• How to check Event Gateway dashboard for event processing
• How to open storefront and verify notification appears
• Troubleshooting common issues

How It Works

Webhook Flow

1. Shopify triggers webhook: When an order is created, Shopify sends an orders/create webhook to the Event Gateway Source
2. Event Gateway receives and queues: The Event Gateway reliably receives and queues the webhook with automatic retries
3. App processes webhook: The Event Gateway delivers the webhook to webhooks.orders.create.tsx, which processes the event
4. Event publication: The app publishes the processed event back to the Event Gateway queue (intended functionality - may not be fully implemented yet)

Real-time Delivery

1. Event Gateway forwarding: The Event Gateway queues and forwards the event to Ably's REST API
2. Pub/Sub broadcast: Ably broadcasts the event to all subscribed clients
3. Storefront receives: The JavaScript in notifications.js receives the event via Ably Realtime
4. UI update: The notification is displayed with festive animations

Theme Extension

The Shopify theme app extension consists of:

• Liquid template: Defines the HTML structure and holiday light animations
• JavaScript: Handles Ably connection, event subscriptions, and snowflake animations
• CSS: Compiled from SCSS, provides styling for animations and layout

Development

Running the App

npm run dev

This starts:

• Remix development server
• Shopify CLI tunnel
• SASS compiler for extension styles

Building for Production

npm run build

Deploying

npm run deploy

This deploys your app extensions to Shopify.

Project Structure

live-notifications/
├── app/
│   ├── routes/
│   │   ├── webhooks.orders.create.tsx    # Order webhook handler
│   │   ├── app._index.tsx                 # App home page
│   │   └── ...
│   ├── helpers/
│   │   └── webhooks.ts                    # Hookdeck/webhook utilities
│   └── shopify.server.ts                  # Shopify app configuration
├── extensions/
│   └── live-notifications/
│       ├── blocks/
│       │   └── notifications.liquid       # Theme block template
│       ├── assets/
│       │   ├── notifications.js           # Client-side logic
│       │   └── notifications.css          # Compiled styles
│       └── src/
│           └── notifications.scss         # Source styles
├── prisma/
│   └── schema.prisma                      # Database schema
├── shopify.app.toml                       # App configuration
└── package.json                           # Dependencies

Technologies Used

• Remix - Full-stack web framework
• Shopify App Remix - Shopify app framework for Remix
• Hookdeck Event Gateway - Webhook infrastructure for reliable delivery and event routing
• Ably - Real-time pub/sub messaging platform
• Prisma - Database ORM
• Shopify Theme App Extensions - Storefront integration

Official Documentation

• Shopify App Development
• Shopify Webhooks
• Shopify Theme App Extensions
• Shopify Admin GraphQL API
• Hookdeck Event Gateway Documentation
• Ably Documentation
• Remix Documentation

Learning Resources

• Shopify App Tutorial
• Webhooks Best Practices
• Theme App Extension Tutorial
• Hookdeck Event Gateway Guide
• Ably Realtime Guide

Limitations & Considerations

• Security: The Ably API key is currently hardcoded in the client-side JavaScript. For production, implement token authentication
• Error Handling: Basic error handling is implemented; production apps should include comprehensive error handling and monitoring
• Scalability: This demo uses a simple SQLite database; production apps should use PostgreSQL or MySQL
• Shop-specific channels: The current implementation creates shop-specific Ably channels to isolate events between stores

License

This is a demonstration/tutorial project for educational purposes.

Author

leggetter

---

Questions or Issues? This is a tutorial app - refer to the official documentation links above for detailed guidance on each technology used.