{"id":28451389,"url":"https://github.com/hookdeck/shopify-festive-notifications","last_synced_at":"2026-05-16T11:33:53.031Z","repository":{"id":283707213,"uuid":"901417287","full_name":"hookdeck/shopify-festive-notifications","owner":"hookdeck","description":"Example Shopify app demonstrating reliable webhook handling with Hookdeck and real-time storefront notifications using Ably.","archived":false,"fork":false,"pushed_at":"2025-12-18T12:42:06.000Z","size":26910,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-21T08:52:04.003Z","etag":null,"topics":["ably","hookdeck","remix-run","shopify","shopify-app","webhooks"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hookdeck.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-10T16:09:43.000Z","updated_at":"2025-12-21T08:31:21.000Z","dependencies_parsed_at":"2025-03-21T17:56:05.983Z","dependency_job_id":"a318a500-7869-4a3a-8758-a27fbc48b79a","html_url":"https://github.com/hookdeck/shopify-festive-notifications","commit_stats":null,"previous_names":["hookdeck/shopify-festive-notifications"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hookdeck/shopify-festive-notifications","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fshopify-festive-notifications","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fshopify-festive-notifications/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fshopify-festive-notifications/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fshopify-festive-notifications/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hookdeck","download_url":"https://codeload.github.com/hookdeck/shopify-festive-notifications/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fshopify-festive-notifications/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33100886,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ably","hookdeck","remix-run","shopify","shopify-app","webhooks"],"created_at":"2025-06-06T16:11:07.816Z","updated_at":"2026-05-16T11:33:53.025Z","avatar_url":"https://github.com/hookdeck.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shopify Festive Real-Time Notifications Demo\n\nA 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.\n\n![Demo of events in the Shop UI with snowflake animations](docs/demo.gif)\n\n## What This Demonstrates\n\nThis is an example/tutorial app that shows developers how to:\n\n- Receive Shopify order webhooks reliably through the Hookdeck Event Gateway\n- Process webhook events in a Remix-based Shopify app\n- Forward events to Ably for real-time pub/sub messaging\n- Display live notifications in a Shopify storefront using theme app extensions\n- Create interactive UI elements with holiday-themed animations\n\n**Note:** This is a demonstration app for learning purposes, not a production-ready application for merchants to install.\n\n## Architecture Overview\n\nThe application uses two Hookdeck Event Gateway connections for reliable webhook processing and real-time delivery:\n\n**Connection 1: Shopify → Event Gateway → App**\n\n- Receives Shopify webhooks reliably\n- Queues and delivers to app with retries\n\n**Connection 2: App → Event Gateway Publish API → Ably**\n\n- Publishes PII-free notifications to Event Gateway\n- Event Gateway forwards to Ably for real-time broadcast\n\n### Flow Diagram\n\n```mermaid\nsequenceDiagram\n    participant Shopify\n    participant EventGateway as Hookdeck Event Gateway\n    participant App as Remix App\u003cbr/\u003e(webhooks.orders.create.tsx)\n    participant Ably\n    participant Storefront as Storefront Extension\u003cbr/\u003e(notifications.js)\n\n    Note over Shopify: 1. Order Created\n    Shopify-\u003e\u003eEventGateway: 2. POST /webhooks (orders/create)\n    Note over EventGateway: 3. Receives \u0026 queues webhook\u003cbr/\u003eat Source (Connection 1)\n    EventGateway-\u003e\u003eApp: 4. Delivers webhook with retries\n    Note over App: 5. Extracts order data\n    App-\u003e\u003eApp: 6. Transform to PII-free notification\n    Note over App: 7. Removes customer PII\u003cbr/\u003eFetches product images\n    App-\u003e\u003eEventGateway: 8. POST to Publish API\u003cbr/\u003e(shopify-notifications-publish)\n    Note over EventGateway: 9. Queues event\u003cbr/\u003e(Connection 2)\n    EventGateway-\u003e\u003eAbly: 10. Forwards to Ably REST API\n    Note over Ably: 11. Broadcasts to channel\n    Ably-\u003e\u003eStorefront: 12. Real-time notification\n    Note over Storefront: 13. Displays notification\u003cbr/\u003ewith snowflake animation\n```\n\n### Step-by-Step Flow\n\n```\n1. Order Created in Shopify\n   ↓\n2. Shopify triggers orders/create webhook\n   ↓\n3. Event Gateway receives and queues the webhook at the Source\n   ↓\n4. Event Gateway delivers webhook to app webhook handler\n   (app/routes/webhooks.orders.create.tsx)\n   ↓\n5. App transforms order to PII-free notification and publishes to Event Gateway\n   (app/helpers/hookdeck-publisher.ts)\n   ↓\n6. Event Gateway queues and forwards event to Ably via REST API\n   ↓\n7. Ably broadcasts to all connected clients\n   ↓\n8. Storefront receives event via Ably Realtime\n   (extensions/live-notifications/assets/notifications.js)\n   ↓\n9. Notification displayed with snowflake animation\n   (extensions/live-notifications/blocks/notifications.liquid)\n```\n\n## Key Components\n\n### Shopify App vs Extension\n\nThis project contains both a **Shopify app** and a **theme app extension**:\n\n- **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.\n- **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.\n\n### Backend (Remix App)\n\n- **[`app/routes/webhooks.orders.create.tsx`](app/routes/webhooks.orders.create.tsx)** - Webhook endpoint that receives order creation events from Shopify via the Event Gateway and publishes PII-free notifications\n- **[`app/helpers/hookdeck-publisher.ts`](app/helpers/hookdeck-publisher.ts)** - Helper functions for publishing events to the Event Gateway, including:\n  - Transforming orders to PII-free notifications (removes customer data)\n  - Fetching product images from Shopify\n  - Publishing to the Event Gateway's Publish API with shop-specific routing\n- **[`scripts/setup-hookdeck.ts`](scripts/setup-hookdeck.ts)** - Automated setup script that creates both Event Gateway connections\n\n### Storefront Extension\n\n- **[`extensions/live-notifications/blocks/notifications.liquid`](extensions/live-notifications/blocks/notifications.liquid)** - Theme app extension block with festive holiday lights and snowfall animations\n- **[`extensions/live-notifications/assets/notifications.js`](extensions/live-notifications/assets/notifications.js)** - Client-side JavaScript that:\n  - Connects to Ably Realtime\n  - Subscribes to notification events\n  - Creates snowflake animations\n  - Handles interactive elements (clickable lights and snowflakes)\n- **[`extensions/live-notifications/src/notifications.scss`](extensions/live-notifications/src/notifications.scss)** - Source SCSS styles (compiled to [`notifications.css`](extensions/live-notifications/assets/notifications.css))\n- **[`extensions/live-notifications/assets/notifications.css`](extensions/live-notifications/assets/notifications.css)** - Compiled CSS (generated from SCSS, not manually edited)\n\n### Configuration\n\n- **[`shopify.app.toml`](shopify.app.toml)** - Shopify app configuration including:\n  - Webhook subscriptions for `orders/create`\n  - Required OAuth scopes (`read_products`, `read_orders`)\n  - App authentication settings\n- **[`package.json`](package.json)** - Dependencies including:\n  - `@shopify/shopify-app-remix` - Shopify app framework\n  - Ably client library (loaded via CDN in storefront)\n\n## Prerequisites\n\nBefore setting up this app, you'll need:\n\n1. **Node.js** (v18.20+, v20.10+, or v21.0.0+)\n2. **Shopify Partner Account** - [Create one here](https://partners.shopify.com/)\n3. **Shopify Development Store** - Create from your Partner Dashboard\n4. **Hookdeck Account** - [Sign up at hookdeck.com](https://dashboard.hookdeck.com/signup?ref=github-shopify-festive-notifications) for the Event Gateway\n5. **Hookdeck CLI** - Install globally with `npm install -g @hookdeck/cli`\n6. **Ably Account** - [Sign up at ably.com](https://ably.com)\n\n## Getting Your API Keys\n\n### Hookdeck API Key\n\n1. Log in to your [Hookdeck Dashboard](https://dashboard.hookdeck.com?ref=github-shopify-festive-notifications)\n2. Navigate to Settings → API Keys\n3. Create or copy your API key\n\n### Ably API Keys\n\nYou'll need **two separate Ably API keys** with different permissions:\n\n**1. Publishing API Key (used in Event Gateway)**\n\nThis key is used by the Event Gateway to forward events to Ably and must have **publish permissions only**.\n\n1. Log in to your [Ably Dashboard](https://ably.com/dashboard)\n2. Navigate to your app → API Keys\n3. Click \"Create new API key\"\n4. Name it \"Event Gateway Publisher\"\n5. Under Capabilities, select **only** \"Publish\"\n6. Copy the full API key (format: `appId.keyId:keySecret`)\n7. Save this key - you'll use it in your `.env` file\n\n**2. Subscribe API Key (for Storefront)**\n\nThis key is used by the storefront extension to receive notifications and must have **subscribe permissions only**.\n\n1. In the Ably Dashboard, create another API key\n2. Name it \"Storefront Subscriber\"\n3. Under Capabilities, select **only** \"Subscribe\"\n4. Copy this API key\n5. Save this key - you'll use it in the extension JavaScript file\n\nLearn more about [Ably API key permissions](https://ably.com/docs/auth/capabilities).\n\n### Shopify Credentials\n\nThe Shopify CLI will automatically configure your app when you run `npm run dev` for the first time:\n\n1. The CLI prompts you to create a new app or select an existing one\n2. The `SHOPIFY_API_KEY` (client_id) is automatically saved to [`shopify.app.toml`](shopify.app.toml)\n3. You need to manually add `SHOPIFY_API_SECRET` to your `.env` file\n\n**To get your `SHOPIFY_API_SECRET`:**\n\n1. Go to your [Shopify Partner Dashboard](https://partners.shopify.com/organizations)\n2. Navigate to Apps → [Your App]\n3. Go to the Configuration tab\n4. Copy the \"Client secret\" value\n5. Add it to your `.env` file as `SHOPIFY_API_SECRET`\n\nThis secret is required for webhook signature verification by the Event Gateway.\n\n## Environment Variables\n\nCreate a `.env` file in the root directory with the following variables:\n\n```env\n# Shopify App Credentials\nSHOPIFY_API_KEY=\nSHOPIFY_API_SECRET=\n\n# Hookdeck Configuration\nHOOKDECK_API_KEY=\n\n# Ably Configuration (use the publishing key)\nABLY_API_KEY=\n```\n\n## Setup Instructions\n\n### 1. Clone and Install\n\n```bash\ngit clone https://github.com/hookdeck/shopify-festive-notifications.git\ncd shopify-festive-notifications\nnpm install\n```\n\n### 2. Configure Ably API Key in Extension\n\nEdit [`extensions/live-notifications/assets/notifications.js`](extensions/live-notifications/assets/notifications.js) and replace the placeholder API key with your **Ably Subscribe API key**:\n\n```javascript\nconst ably = new Ably.Realtime(\"YOUR_ABLY_SUBSCRIBE_API_KEY\");\n```\n\n**Important:** Use the subscribe-only API key here, not the publishing key from your `.env` file.\n\n**Note:** In production, this should be handled more securely using token authentication.\n\n### 3. Install and Configure Hookdeck CLI\n\nThe Hookdeck CLI is required for this demo application to receive webhooks locally.\n\n1. **Install Hookdeck CLI globally:**\n\n   ```bash\n   npm install -g @hookdeck/cli\n   ```\n\n2. **Login to Hookdeck:**\n\n   ```bash\n   hookdeck login\n   ```\n\n   This authenticates the CLI with your Hookdeck account.\n\n### 4. Configure Shopify App\n\n```bash\nnpm run dev\n```\n\nThis will:\n\n- Create a tunnel for local development (using Cloudflare)\n- Prompt you to create/select a Shopify app\n- Install the app on your development store\n- Start the development server\n\n**Note on Tunneling:**\n\n- The Cloudflare tunnel created by `npm run dev` is **required** for Shopify to communicate with your local app (OAuth, app embeds, admin interface)\n- The Hookdeck CLI is used to receive webhooks locally and provides better debugging capabilities\n- Both run simultaneously: Cloudflare tunnel for the app, Hookdeck CLI for webhooks\n\n**Benefits of Hookdeck CLI for webhooks:**\n\n- Real-time webhook inspection and debugging\n- Replay webhooks during development\n- Test different payloads easily\n- View webhook history and errors\n- No need to trigger real Shopify events repeatedly\n\n### 5. Configure Event Gateway Connections\n\nRun the automated setup script to create both Event Gateway connections:\n\n```bash\nnpm run setup:hookdeck\n```\n\nThis script automatically creates:\n\n1. **Connection 1: Shopify → App**\n\n   - Source: `shopify-webhooks` (for receiving webhooks from Shopify)\n   - Destination: Points to your app's webhook handler\n   - CLI Connection: For local development\n   - **Webhook Signing**: Automatically configured using your `SHOPIFY_API_SECRET` to verify webhook authenticity\n\n2. **Connection 2: App → Ably**\n   - Source: `shopify-notifications-publish` (for publishing from your app)\n   - Destination: `ably-rest-api` (forwards to Ably REST API)\n   - Authentication: Uses your Ably publishing API key from `.env`\n   - Routing: Shop-specific channels for multi-tenant support\n\nThe script uses your `ABLY_API_KEY` and `SHOPIFY_API_SECRET` from `.env` to configure connections automatically.\n\n**Note:** For production deployments, you'll need to update the destination URL in Connection 1 to point to your production server instead of localhost.\n\n### 6. Start Hookdeck CLI for Local Webhook Development\n\nIn a second terminal, start the Hookdeck CLI to forward webhooks to your local server:\n\n```bash\nnpm run hookdeck:listen\n```\n\n\u003e [!NOTE]\n\u003e This runs the command:\n\u003e\n\u003e ```bash\n\u003e hookdeck listen 3000 shopify-webhooks\n\u003e ```\n\nThis creates or reuses an Event Gateway Connection that forwards events from a `shopify-webhooks` Source to `localhost:3000`. Keep this terminal running.\n\n### 7. Enable the Theme Extension\n\n1. Go to your Shopify admin → Online Store → Themes\n2. Click \"Customize\" on your active theme\n3. Navigate to any page in the theme editor\n4. Click \"Add section\" or \"Add block\"\n5. Look for \"Festive Notifications\" under App blocks\n6. Add it to your theme (typically in the theme layout or header)\n7. Save and publish\n\n### 8. Test the Integration\n\nSee [`docs/TESTING.md`](docs/TESTING.md) for detailed testing instructions including:\n\n- Step-by-step guide to creating a test order\n- How to verify webhook delivery in app logs\n- How to check the Event Gateway dashboard for event processing\n- How to verify notifications appear in the storefront\n- Troubleshooting common issues\n\n## How It Works\n\n### Webhook Flow\n\n1. **Shopify triggers webhook**: When an order is created, Shopify sends an `orders/create` webhook to the Event Gateway Source\n2. **Event Gateway receives and queues**: The Event Gateway reliably receives and queues the webhook with automatic retries\n3. **App processes webhook**: The Event Gateway delivers the webhook to [`webhooks.orders.create.tsx`](app/routes/webhooks.orders.create.tsx)\n4. **PII filtering**: The webhook handler extracts order data and uses [`hookdeck-publisher.ts`](app/helpers/hookdeck-publisher.ts) to:\n   - Remove customer PII (name, email, address)\n   - Fetch product images from Shopify\n   - Create a clean notification payload\n5. **Event publication**: The app publishes the PII-free notification to the Event Gateway's Publish API with shop-specific routing\n\n### Real-time Delivery\n\n1. **Event Gateway forwarding**: The Event Gateway queues and forwards the event to Ably's REST API via the configured destination\n2. **Pub/Sub broadcast**: Ably broadcasts the event to all subscribed clients on the shop-specific channel\n3. **Storefront receives**: The JavaScript in [`notifications.js`](extensions/live-notifications/assets/notifications.js) receives the event via Ably Realtime\n4. **UI update**: The notification is displayed with product image and festive snowflake animations\n\n### Theme Extension\n\nThe Shopify theme app extension consists of:\n\n- **Liquid template**: Defines the HTML structure and holiday light animations\n- **JavaScript**: Handles Ably connection, event subscriptions, and snowflake animations\n- **CSS**: Compiled from SCSS, provides styling for animations and layout\n\n## Development\n\n### Running the App\n\n```bash\nnpm run dev\n```\n\nThis starts:\n\n- Remix development server\n- Shopify CLI tunnel\n- SASS compiler for extension styles\n\n### Building for Production\n\n```bash\nnpm run build\n```\n\n### Deploying\n\n```bash\nnpm run deploy\n```\n\nThis deploys your app extensions to Shopify.\n\n## Project Structure\n\n```\nlive-notifications/\n├── app/\n│   ├── routes/\n│   │   ├── webhooks.orders.create.tsx    # Order webhook handler\n│   │   ├── app._index.tsx                 # App home page\n│   │   └── ...\n│   ├── helpers/\n│   │   └── hookdeck-publisher.ts          # Event Gateway publishing utilities\n│   └── shopify.server.ts                  # Shopify app configuration\n├── extensions/\n│   └── live-notifications/\n│       ├── blocks/\n│       │   └── notifications.liquid       # Theme block template\n│       ├── assets/\n│       │   ├── notifications.js           # Client-side logic\n│       │   └── notifications.css          # Compiled styles\n│       └── src/\n│           └── notifications.scss         # Source styles\n├── scripts/\n│   └── setup-hookdeck.ts                  # Automated connection setup\n├── plans/\n│   ├── hookdeck-ably-architecture.md      # Architecture documentation\n│   └── hookdeck-setup-architecture.md     # Setup process documentation\n├── docs/\n│   └── TESTING.md                         # Testing guide\n├── prisma/\n│   └── schema.prisma                      # Database schema\n├── shopify.app.toml                       # App configuration\n└── package.json                           # Dependencies\n```\n\n## Technologies Used\n\n- **[Remix](https://remix.run/)** - Full-stack web framework\n- **[Shopify App Remix](https://shopify.dev/docs/api/shopify-app-remix)** - Shopify app framework for Remix\n- **[Hookdeck Event Gateway](https://hookdeck.com?ref=github-shopify-festive-notifications)** - Webhook infrastructure for reliable delivery and event routing\n- **[Ably](https://ably.com)** - Real-time pub/sub messaging platform\n- **[Prisma](https://www.prisma.io/)** - Database ORM\n- **[Shopify Theme App Extensions](https://shopify.dev/docs/apps/online-store/theme-app-extensions)** - Storefront integration\n\n## Official Documentation\n\n- [Shopify App Development](https://shopify.dev/docs/apps)\n- [Shopify Webhooks](https://shopify.dev/docs/apps/build/webhooks)\n- [Shopify Theme App Extensions](https://shopify.dev/docs/apps/online-store/theme-app-extensions)\n- [Shopify Admin GraphQL API](https://shopify.dev/docs/api/admin-graphql)\n- [Hookdeck Event Gateway Documentation](https://hookdeck.com/docs?ref=github-shopify-festive-notifications)\n- [Ably Documentation](https://ably.com/docs)\n- [Remix Documentation](https://remix.run/docs)\n\n## Learning Resources\n\n- [Shopify App Tutorial](https://shopify.dev/docs/apps/getting-started)\n- [Webhooks Best Practices](https://shopify.dev/docs/apps/build/webhooks/best-practices)\n- [Theme App Extension Tutorial](https://shopify.dev/docs/apps/online-store/theme-app-extensions/getting-started)\n- [Hookdeck Event Gateway Guide](https://hookdeck.com/webhooks?ref=github-shopify-festive-notifications)\n- [Ably Realtime Guide](https://ably.com/docs/realtime)\n\n## Limitations \u0026 Considerations\n\n- **Security**: The Ably API key is currently hardcoded in the client-side JavaScript. For production, implement token authentication\n- **Error Handling**: Basic error handling is implemented; production apps should include comprehensive error handling and monitoring\n- **Scalability**: This demo uses a simple SQLite database; production apps should use PostgreSQL or MySQL\n- **Shop-specific channels**: The current implementation creates shop-specific Ably channels to isolate events between stores\n\n## License\n\nThis is a demonstration/tutorial project for educational purposes.\n\n## Author\n\nleggetter\n\n---\n\n**Questions or Issues?** This is a tutorial app - refer to the official documentation links above for detailed guidance on each technology used.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhookdeck%2Fshopify-festive-notifications","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhookdeck%2Fshopify-festive-notifications","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhookdeck%2Fshopify-festive-notifications/lists"}