Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added supoort for webhooks in SDK and next packages
Damian Legawiecb0c2ce9abaf7
diff --git a/docker-compose.yml b/docker-compose.ymlindex 9dcfa00b66..ed9d4bff93 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -17,8 +17,8 @@ x-app: &appRAILS_FORCE_SSL: "false"RAILS_ASSUME_SSL: "false"MEILISEARCH_URL: http://meilisearch:7700- SMTP_HOST: mailpit- SMTP_PORT: "1025"+ # Admin/system emails use letter_opener in development (opens in browser).+ # Customer transactional emails are handled by the storefront via webhooks.services:postgres:@@ -59,12 +59,6 @@ services:timeout: 5sretries: 5- mailpit:- image: axllent/mailpit- ports:- - "8025:8025"- - "1025:1025"-web:<<: *appports:diff --git a/docs/developer/core-concepts/webhooks.mdx b/docs/developer/core-concepts/webhooks.mdxindex 3e6bcee0c1..eb8b5aef12 100644--- a/docs/developer/core-concepts/webhooks.mdx+++ b/docs/developer/core-concepts/webhooks.mdx@@ -163,22 +163,56 @@ Each webhook request includes these headers:### Verifying Webhook Signatures-To ensure webhooks are genuinely from your Spree store, verify the signature:+To ensure webhooks are genuinely from your Spree store, verify the signature.++#### Next.js (recommended)++Use `@spree/next/webhooks` for a ready-made Route Handler:++```typescript+// src/app/api/webhooks/spree/route.ts+import { createWebhookHandler } from '@spree/next/webhooks'++export const POST = createWebhookHandler({+ secret: process.env.SPREE_WEBHOOK_SECRET!,+ handlers: {+ 'order.completed': async (event) => {+ // event.data is the order payload (same shape as Store API)+ await sendOrderConfirmationEmail(event.data)+ },+ 'order.canceled': async (event) => {+ await sendCancellationEmail(event.data)+ },+ },+})+```-```ruby-# In your webhook receiver-def verify_webhook(request)- payload = request.body.read- signature = request.headers['X-Spree-Webhook-Signature']- secret_key = ENV['SPREE_WEBHOOK_SECRET'] # Your endpoint's secret_key+#### Any JavaScript/TypeScript framework- expected = OpenSSL::HMAC.hexdigest('SHA256', secret_key, payload)+Use `@spree/sdk/webhooks` for framework-agnostic verification:- ActiveSupport::SecurityUtils.secure_compare(signature, expected)-end+```typescript+import { verifyWebhookSignature } from '@spree/sdk/webhooks'+import type { WebhookEvent } from '@spree/sdk/webhooks'+import type { Order } from '@spree/sdk'++// Hono, Cloudflare Workers, or any Web Fetch API-based framework+app.post('/webhooks/spree', async (req, res) => {+ const body = await req.text()+ const signature = req.headers['x-spree-webhook-signature']+ const timestamp = req.headers['x-spree-webhook-timestamp']++ if (!verifyWebhookSignature(body, signature, timestamp, process.env.SPREE_WEBHOOK_SECRET!)) {+ return res.status(401).json({ error: 'Invalid signature' })+ }++ const event: WebhookEvent<Order> = JSON.parse(body)+ // handle event...+ res.json({ received: true })+})```-Example in a Rails controller:+#### Ruby```rubyclass WebhooksController < ApplicationController@@ -209,7 +243,8 @@ class WebhooksController < ApplicationControllerrequest.body.rewindsignature = request.headers['X-Spree-Webhook-Signature']- expected = OpenSSL::HMAC.hexdigest('SHA256', ENV['SPREE_WEBHOOK_SECRET'], payload)+ timestamp = request.headers['X-Spree-Webhook-Timestamp']+ expected = OpenSSL::HMAC.hexdigest('SHA256', ENV['SPREE_WEBHOOK_SECRET'], "#{timestamp}.#{payload}")ActiveSupport::SecurityUtils.secure_compare(signature.to_s, expected)enddiff --git a/docs/developer/storefront/nextjs/spree-next-package.mdx b/docs/developer/storefront/nextjs/spree-next-package.mdxindex 9f6309a665..12adb0cb97 100644--- a/docs/developer/storefront/nextjs/spree-next-package.mdx+++ b/docs/developer/storefront/nextjs/spree-next-package.mdx@@ -20,6 +20,9 @@ Set environment variables and the client initializes automatically:```envSPREE_API_URL=https://api.mystore.comSPREE_PUBLISHABLE_KEY=spree_pk_xxx++# Required for webhook-based emails (see Webhooks section below)+SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key```### Explicit initialization@@ -284,6 +287,48 @@ const products = await listProducts({ limit: 10 }, { locale: 'fr', country: 'FR'const category = await getCategory('clothing/shirts', {}, { locale: 'de', country: 'DE' });```+## Webhooks++Handle Spree webhook events in your Next.js app with `@spree/next/webhooks`:++```typescript+// src/app/api/webhooks/spree/route.ts+import { createWebhookHandler } from '@spree/next/webhooks'++export const POST = createWebhookHandler({+ secret: process.env.SPREE_WEBHOOK_SECRET!,+ handlers: {+ 'order.completed': async (event) => {+ await sendOrderConfirmationEmail(event.data)+ },+ 'order.canceled': async (event) => {+ await sendCancellationEmail(event.data)+ },+ 'order.shipped': async (event) => {+ await sendShippingNotification(event.data)+ },+ 'customer.password_reset_requested': async (event) => {+ await sendPasswordResetEmail(event.data)+ },+ },+})+```++The handler verifies HMAC-SHA256 signatures, rejects replayed requests, routes events to your handlers, and returns 200 immediately (handlers run async).++### Local development++Webhooks require a publicly accessible URL. Use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/) for local development:++```bash+brew install cloudflared+cloudflared tunnel --url http://localhost:3001+```++Then create a webhook endpoint in **Spree Admin → Settings → Developers → Webhooks** pointing to your tunnel URL + `/api/webhooks/spree`.++For more details, see [Webhooks](/developer/core-concepts/webhooks).+## TypeScriptAll types are re-exported from `@spree/sdk`:diff --git a/packages/next/CHANGELOG.md b/packages/next/CHANGELOG.mdindex 6793be4610..74c766c6f7 100644--- a/packages/next/CHANGELOG.md+++ b/packages/next/CHANGELOG.md@@ -1,5 +1,13 @@# @spree/next+## 0.17.0++### New Features++- **Webhook Route Handler** — new `@spree/next/webhooks` subpath export with `createWebhookHandler()` factory. Creates a Next.js Route Handler that verifies HMAC-SHA256 signatures, parses events, and dispatches to user-defined handlers. Returns 200 immediately and processes handlers async.++Requires `@spree/sdk >= 0.16.0`.+## 0.16.0### Breaking Changesdiff --git a/packages/next/README.md b/packages/next/README.mdindex 0c591c6a87..bd05a06d88 100644--- a/packages/next/README.md+++ b/packages/next/README.md@@ -323,6 +323,47 @@ You can still pass locale options explicitly — they override auto-detected valconst products = await listProducts({ limit: 10 }, { locale: 'fr', country: 'FR' });```+## Webhooks++Handle Spree webhook events in your Next.js app with a single function:++```typescript+// src/app/api/webhooks/spree/route.ts+import { createWebhookHandler } from '@spree/next/webhooks';++export const POST = createWebhookHandler({+ secret: process.env.SPREE_WEBHOOK_SECRET!,+ handlers: {+ 'order.completed': async (event) => {+ const order = event.data; // typed as the data you pass+ await sendOrderConfirmationEmail(order);+ },+ 'order.canceled': async (event) => {+ await sendCancellationEmail(event.data);+ },+ 'shipment.shipped': async (event) => {+ await sendShippingNotification(event.data);+ },+ },+});+```++`createWebhookHandler` handles:+- HMAC-SHA256 signature verification (via `@spree/sdk/webhooks`)+- Replay protection (rejects timestamps older than 5 minutes)+- Event routing to your handlers by event name+- Returns 200 immediately, processes handlers async (Spree won't time out)+- Unhandled events return 200 with `{ handled: false }` (no retries)++### Setup++1. Install [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/) for local development: `brew install cloudflared`+2. Expose your storefront: `cloudflared tunnel --url http://localhost:3001`+3. Create a webhook endpoint in **Spree Admin → Settings → Developers → Webhooks** pointing to your tunnel URL + `/api/webhooks/spree`+4. Add `SPREE_WEBHOOK_SECRET` to your `.env.local`++For framework-agnostic webhook verification (Express, Hono, etc.), use `@spree/sdk/webhooks` directly — see the [`@spree/sdk` README](../sdk/README.md#webhooks).+## TypeScriptAll types are re-exported from `@spree/sdk` for convenience:diff --git a/packages/next/package.json b/packages/next/package.jsonindex cdd9b64259..fd2887a3af 100644--- a/packages/next/package.json+++ b/packages/next/package.json@@ -1,6 +1,6 @@{"name": "@spree/next",- "version": "0.16.0",+ "version": "0.17.0","description": "Next.js integration for Spree Commerce — server actions, caching, and cookie-based auth","type": "module","main": "./dist/index.js",@@ -23,6 +23,13 @@"default": "./dist/middleware.js"},"default": "./dist/middleware.js"+ },+ "./webhooks": {+ "import": {+ "types": "./dist/webhooks.d.ts",+ "default": "./dist/webhooks.js"+ },+ "default": "./dist/webhooks.js"}},"files": [diff --git a/packages/next/src/webhooks.ts b/packages/next/src/webhooks.tsnew file mode 100644index 0000000000..38ecdc832c--- /dev/null+++ b/packages/next/src/webhooks.ts@@ -0,0 +1,125 @@+import { NextResponse } from 'next/server'+import { verifyWebhookSignature } from '@spree/sdk/webhooks'+import type { WebhookEvent } from '@spree/sdk/webhooks'++export type { WebhookEvent }++export type WebhookHandler<T = any> = (event: WebhookEvent<T>) => Promise<void>++export interface CreateWebhookHandlerOptions {+ /**+ * The webhook endpoint secret key (from Spree Admin → Webhooks).+ * Usually: `process.env.SPREE_WEBHOOK_SECRET`+ */+ secret: string++ /**+ * Map of event names to handler functions.+ * Unhandled events return 200 with `{ handled: false }` so Spree doesn't retry.+ *+ * @example+ * {+ * 'order.completed': handleOrderCompleted,+ * 'order.canceled': handleOrderCanceled,+ * }+ */+ handlers: Record<string, WebhookHandler>++ /**+ * Max age of the webhook timestamp in seconds before rejecting (replay protection).+ * @default 300 (5 minutes)+ */+ toleranceSeconds?: number++ /**+ * Optional `waitUntil` function for extending serverless execution context.+ * On Vercel/Cloudflare, pass `waitUntil` from the request context to ensure+ * handlers complete even after the response is sent.+ *+ * If not provided, handlers are awaited before returning the response.+ *+ * @example+ * ```ts+ * // Vercel with waitUntil+ * import { waitUntil } from '@vercel/functions'+ *+ * export const POST = createWebhookHandler({+ * secret: process.env.SPREE_WEBHOOK_SECRET!,+ * waitUntil,+ * handlers: { ... },+ * })+ * ```+ */+ waitUntil?: (promise: Promise<unknown>) => void+}++/**+ * Creates a Next.js Route Handler for Spree webhooks.+ *+ * Handles signature verification, event parsing, and dispatching to your handlers.+ *+ * @example+ * ```ts+ * // src/app/api/webhooks/spree/route.ts+ * import { createWebhookHandler } from '@spree/next/webhooks'+ *+ * export const POST = createWebhookHandler({+ * secret: process.env.SPREE_WEBHOOK_SECRET!,+ * handlers: {+ * 'order.completed': async (event) => { ... },+ * 'order.canceled': async (event) => { ... },+ * },+ * })+ * ```+ */+export function createWebhookHandler(options: CreateWebhookHandlerOptions) {+ const { secret, handlers, toleranceSeconds, waitUntil } = options++ return async function POST(request: Request) {+ if (!secret) {+ console.error('[spree-webhook] Secret is not configured')+ return NextResponse.json({ error: 'Webhook secret not configured' }, { status: 500 })+ }++ const body = await request.text()+ const signature = request.headers.get('x-spree-webhook-signature')+ const timestamp = request.headers.get('x-spree-webhook-timestamp')+ const eventName = request.headers.get('x-spree-webhook-event')++ if (!signature || !timestamp) {+ return NextResponse.json({ error: 'Missing signature headers' }, { status: 401 })+ }++ if (!verifyWebhookSignature(body, signature, timestamp, secret, toleranceSeconds)) {+ return NextResponse.json({ error: 'Invalid signature' }, { status: 401 })+ }++ let event: WebhookEvent+ try {+ event = JSON.parse(body)+ } catch {+ return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 })+ }++ const name = eventName || event.name+ const handler = handlers[name]++ if (!handler) {+ return NextResponse.json({ received: true, handled: false })+ }++ const work = handler(event).catch((error) => {+ console.error(`[spree-webhook] Error handling ${name}:`, error)+ })++ if (waitUntil) {+ // Serverless: schedule background work and return immediately+ waitUntil(work)+ } else {+ // Default: await the handler before responding+ await work+ }++ return NextResponse.json({ received: true, handled: true })+ }+}diff --git a/packages/next/tests/webhooks.test.ts b/packages/next/tests/webhooks.test.tsnew file mode 100644index 0000000000..2d1eef3d14--- /dev/null+++ b/packages/next/tests/webhooks.test.ts@@ -0,0 +1,247 @@+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'+import { createHmac } from 'node:crypto'+import { createWebhookHandler } from '../src/webhooks'++function sign(payload: string, secret: string, timestamp: number): string {+ return createHmac('sha256', secret)+ .update(`${timestamp}.${payload}`)+ .digest('hex')+}++function buildRequest(body: string, headers: Record<string, string> = {}): Request {+ return new Request('http://localhost/api/webhooks/spree', {+ method: 'POST',+ body,+ headers: {+ 'content-type': 'application/json',+ ...headers,+ },+ })+}++const SECRET = 'test_webhook_secret_key'++function signedRequest(payload: object, timestamp?: number) {+ const ts = timestamp ?? Math.floor(Date.now() / 1000)+ const body = JSON.stringify(payload)+ const signature = sign(body, SECRET, ts)++ return buildRequest(body, {+ 'x-spree-webhook-signature': signature,+ 'x-spree-webhook-timestamp': String(ts),+ 'x-spree-webhook-event': (payload as any).name || '',+ })+}++describe('createWebhookHandler', () => {+ beforeEach(() => {+ vi.useFakeTimers()+ vi.setSystemTime(new Date('2026-01-15T12:00:00Z'))+ })++ afterEach(() => {+ vi.useRealTimers()+ })++ const orderPayload = {+ id: 'evt_123',+ name: 'order.completed',+ created_at: '2026-01-15T12:00:00Z',+ data: { number: 'R123', email: '[email protected]' },+ metadata: { spree_version: '5.4.0' },+ }++ it('dispatches to the correct handler and returns 200', async () => {+ const handler = vi.fn().mockResolvedValue(undefined)+ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: { 'order.completed': handler },+ })++ const response = await POST(signedRequest(orderPayload))+ const json = await response.json()++ expect(response.status).toBe(200)+ expect(json).toEqual({ received: true, handled: true })+ expect(handler).toHaveBeenCalledWith(orderPayload)+ })++ it('returns 200 with handled: false for unhandled events', async () => {+ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: {},+ })++ const response = await POST(signedRequest(orderPayload))+ const json = await response.json()++ expect(response.status).toBe(200)+ expect(json).toEqual({ received: true, handled: false })+ })++ it('returns 401 when signature is missing', async () => {+ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: { 'order.completed': vi.fn() },+ })++ const request = buildRequest(JSON.stringify(orderPayload))+ const response = await POST(request)++ expect(response.status).toBe(401)+ })++ it('returns 401 when signature is invalid', async () => {+ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: { 'order.completed': vi.fn() },+ })++ const ts = Math.floor(Date.now() / 1000)+ const request = buildRequest(JSON.stringify(orderPayload), {+ 'x-spree-webhook-signature': 'invalid',+ 'x-spree-webhook-timestamp': String(ts),+ })+ const response = await POST(request)++ expect(response.status).toBe(401)+ })++ it('returns 400 for invalid JSON', async () => {+ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: { 'order.completed': vi.fn() },+ })++ const body = 'not-json'+ const ts = Math.floor(Date.now() / 1000)+ const signature = sign(body, SECRET, ts)++ const request = buildRequest(body, {+ 'x-spree-webhook-signature': signature,+ 'x-spree-webhook-timestamp': String(ts),+ })+ const response = await POST(request)++ expect(response.status).toBe(400)+ })++ it('returns 500 when secret is empty', async () => {+ const POST = createWebhookHandler({+ secret: '',+ handlers: { 'order.completed': vi.fn() },+ })++ const response = await POST(signedRequest(orderPayload))++ expect(response.status).toBe(500)+ })++ it('awaits handler when no waitUntil is provided', async () => {+ const order: string[] = []+ const handler = vi.fn(async () => {+ order.push('handler')+ })++ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: { 'order.completed': handler },+ })++ await POST(signedRequest(orderPayload))+ order.push('after-response')++ expect(order).toEqual(['handler', 'after-response'])+ })++ it('uses waitUntil when provided and returns before handler completes', async () => {+ let scheduledPromise: Promise<unknown> | null = null+ const waitUntil = vi.fn((p: Promise<unknown>) => { scheduledPromise = p })++ const handler = vi.fn(async () => {+ // simulate slow work+ })++ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: { 'order.completed': handler },+ waitUntil,+ })++ const response = await POST(signedRequest(orderPayload))++ expect(response.status).toBe(200)+ expect(waitUntil).toHaveBeenCalledOnce()+ expect(scheduledPromise).toBeInstanceOf(Promise)++ // Resolve the background work+ await scheduledPromise+ expect(handler).toHaveBeenCalledWith(orderPayload)+ })++ it('uses event name from header over payload', async () => {+ const completedHandler = vi.fn().mockResolvedValue(undefined)+ const canceledHandler = vi.fn().mockResolvedValue(undefined)++ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: {+ 'order.completed': completedHandler,+ 'order.canceled': canceledHandler,+ },+ })++ // Payload says completed, but header overrides to canceled+ const ts = Math.floor(Date.now() / 1000)+ const body = JSON.stringify(orderPayload)+ const signature = sign(body, SECRET, ts)++ const request = buildRequest(body, {+ 'x-spree-webhook-signature': signature,+ 'x-spree-webhook-timestamp': String(ts),+ 'x-spree-webhook-event': 'order.canceled',+ })++ await POST(request)++ expect(canceledHandler).toHaveBeenCalled()+ expect(completedHandler).not.toHaveBeenCalled()+ })++ it('logs handler errors without failing the response', async () => {+ const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})+ const handler = vi.fn().mockRejectedValue(new Error('email send failed'))++ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: { 'order.completed': handler },+ })++ const response = await POST(signedRequest(orderPayload))++ expect(response.status).toBe(200)+ expect(consoleSpy).toHaveBeenCalledWith(+ expect.stringContaining('order.completed'),+ expect.any(Error),+ )++ consoleSpy.mockRestore()+ })++ it('respects custom tolerance', async () => {+ const handler = vi.fn().mockResolvedValue(undefined)++ const POST = createWebhookHandler({+ secret: SECRET,+ handlers: { 'order.completed': handler },+ toleranceSeconds: 10,+ })++ // Timestamp is 30 seconds old — outside 10s tolerance+ const oldTs = Math.floor(Date.now() / 1000) - 30+ const response = await POST(signedRequest(orderPayload, oldTs))++ expect(response.status).toBe(401)+ expect(handler).not.toHaveBeenCalled()+ })+})diff --git a/packages/next/tsup.config.ts b/packages/next/tsup.config.tsindex 23cafd2dc0..545f8758c4 100644--- a/packages/next/tsup.config.ts+++ b/packages/next/tsup.config.ts@@ -52,4 +52,15 @@ export default defineConfig([sourcemap: true,external: ['next', 'next/server', '@spree/sdk'],},+ // Webhooks — separate entry (uses next/server + @spree/sdk/webhooks)+ {+ entry: {+ webhooks: 'src/webhooks.ts',+ },+ format: ['esm'],+ dts: true,+ splitting: false,+ sourcemap: true,+ external: ['next', 'next/server', '@spree/sdk', '@spree/sdk/webhooks'],+ },]);diff --git a/packages/sdk/.changeset/product-description-html.md b/packages/sdk/.changeset/product-description-html.mddeleted file mode 100644index c0737adebe..0000000000--- a/packages/sdk/.changeset/product-description-html.md+++ /dev/null@@ -1,5 +0,0 @@-----"@spree/sdk": patch------Add `description_html` field to Product type. The `description` field now returns plain text (HTML tags stripped), while `description_html` returns the raw HTML. This aligns Product with the existing Category pattern.diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.mdindex 454af0c4d8..6767012b9b 100644--- a/packages/sdk/CHANGELOG.md+++ b/packages/sdk/CHANGELOG.md@@ -1,5 +1,12 @@# @spree/sdk+## 0.17.0++### New Features++- **Webhook signature verification** — new `@spree/sdk/webhooks` subpath export with `verifyWebhookSignature()` for HMAC-SHA256 signature verification with replay protection. Works with any framework (Express, Hono, Cloudflare Workers, Next.js, etc.)+- **Webhook event types** — `WebhookEvent<T>` generic envelope type. Use existing SDK types (`Order`, `Payment`, `Fulfillment`, etc.) as the type parameter — webhook payloads use the same V3 serializers as the REST API+## 0.16.0### Breaking Changesdiff --git a/packages/sdk/README.md b/packages/sdk/README.mdindex 70d7a9e358..e0a76fb57a 100644--- a/packages/sdk/README.md+++ b/packages/sdk/README.md@@ -760,6 +760,35 @@ const client = createClient({});```+## Webhooks++The SDK includes webhook signature verification and types via the `@spree/sdk/webhooks` subpath:++```typescript+import { verifyWebhookSignature, type WebhookEvent } from '@spree/sdk/webhooks';+import type { Order } from '@spree/sdk';++// Verify a webhook signature (works with any framework)+const isValid = verifyWebhookSignature(+ rawBody, // raw request body string+ request.headers.get('x-spree-webhook-signature')!, // HMAC signature+ request.headers.get('x-spree-webhook-timestamp')!, // unix timestamp+ process.env.SPREE_WEBHOOK_SECRET! // endpoint secret key+);++// Type your webhook handlers using SDK types+type OrderEvent = WebhookEvent<Order>;++function handleOrderCompleted(event: OrderEvent) {+ const order = event.data; // fully typed Order+ console.log(order.number, order.email, order.display_total);+}+```++Webhook payloads use the same V3 serializers as the REST API, so all SDK types (`Order`, `Cart`, `Payment`, `Fulfillment`, etc.) work directly as the `data` field type.++For **Next.js** projects, use `@spree/next/webhooks` for a ready-made Route Handler — see [`@spree/next` README](../next/README.md#webhooks).+## Development### Setupdiff --git a/packages/sdk/package.json b/packages/sdk/package.jsonindex 9815b098bf..ffc152bc6b 100644--- a/packages/sdk/package.json+++ b/packages/sdk/package.json@@ -1,6 +1,6 @@{"name": "@spree/sdk",- "version": "0.16.0",+ "version": "0.17.0","description": "Official TypeScript SDK for Spree Commerce Store API","type": "module","main": "./dist/index.cjs",@@ -36,6 +36,16 @@"types": "./dist/zod/index.d.cts","default": "./dist/zod/index.cjs"}+ },+ "./webhooks": {+ "import": {+ "types": "./dist/webhooks.d.ts",+ "default": "./dist/webhooks.js"+ },+ "require": {+ "types": "./dist/webhooks.d.cts",+ "default": "./dist/webhooks.cjs"+ }}},"files": [diff --git a/packages/sdk/src/webhooks.ts b/packages/sdk/src/webhooks.tsnew file mode 100644index 0000000000..5a88efd153--- /dev/null+++ b/packages/sdk/src/webhooks.ts@@ -0,0 +1,85 @@+import { createHmac, timingSafeEqual } from 'node:crypto'++// ─── Verification ──────────────────────────────────────────────++/**+ * Verifies the HMAC-SHA256 signature of a Spree webhook request.+ *+ * Spree signs webhooks as: HMAC-SHA256(secret, "{timestamp}.{payload}")+ * with headers X-Spree-Webhook-Signature and X-Spree-Webhook-Timestamp.+ *+ * @param payload - Raw request body string+ * @param signature - Value of X-Spree-Webhook-Signature header+ * @param timestamp - Value of X-Spree-Webhook-Timestamp header+ * @param secret - The webhook endpoint's secret key+ * @param toleranceSeconds - Max age of the timestamp in seconds (default: 300 = 5 min)+ *+ * @example+ * ```ts+ * import { verifyWebhookSignature } from '@spree/sdk/webhooks'+ *+ * const isValid = verifyWebhookSignature(+ * rawBody,+ * request.headers['x-spree-webhook-signature'],+ * request.headers['x-spree-webhook-timestamp'],+ * process.env.SPREE_WEBHOOK_SECRET+ * )+ * ```+ */+export function verifyWebhookSignature(+ payload: string,+ signature: string,+ timestamp: string,+ secret: string,+ toleranceSeconds = 300,+): boolean {+ const ts = Number.parseInt(timestamp, 10)+ if (Number.isNaN(ts)) return false++ const age = Math.abs(Math.floor(Date.now() / 1000) - ts)+ if (age > toleranceSeconds) return false++ const expected = createHmac('sha256', secret)+ .update(`${timestamp}.${payload}`)+ .digest('hex')++ try {+ return timingSafeEqual(Buffer.from(signature), Buffer.from(expected))+ } catch {+ return false+ }+}++// ─── Types ─────────────────────────────────────────────────────++/**+ * Spree webhook event envelope.+ *+ * The `data` field contains the serialized resource using the same+ * Store API V3 serializers as the REST API. Use the SDK's existing types+ * (e.g. `Cart`, `Order`, `Payment`, `Fulfillment`) for the `data` field.+ *+ * @example+ * ```ts+ * import type { WebhookEvent } from '@spree/sdk/webhooks'+ * import type { Order, Payment } from '@spree/sdk'+ *+ * // Order events (order.completed, order.canceled, etc.)+ * type OrderEvent = WebhookEvent<Order>+ *+ * // Payment events (payment.paid, etc.)+ * type PaymentEvent = WebhookEvent<Payment>+ *+ * // Custom event with ad-hoc payload+ * type PasswordResetEvent = WebhookEvent<{ email: string; reset_token: string }>+ * ```+ */+export interface WebhookEvent<T = unknown> {+ id: string+ name: string+ created_at: string+ data: T+ metadata: {+ spree_version: string+ }+}diff --git a/packages/sdk/tests/webhooks.test.ts b/packages/sdk/tests/webhooks.test.tsnew file mode 100644index 0000000000..1ab399d8b3--- /dev/null+++ b/packages/sdk/tests/webhooks.test.ts@@ -0,0 +1,117 @@+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'+import { createHmac } from 'node:crypto'+import { verifyWebhookSignature, type WebhookEvent } from '../src/webhooks'++function sign(payload: string, secret: string, timestamp: number): string {+ return createHmac('sha256', secret)+ .update(`${timestamp}.${payload}`)+ .digest('hex')+}++describe('verifyWebhookSignature', () => {+ const secret = 'test_secret_key_abc123'+ const payload = '{"id":"evt_123","name":"order.completed","data":{}}'++ beforeEach(() => {+ vi.useFakeTimers()+ vi.setSystemTime(new Date('2026-01-15T12:00:00Z'))+ })++ afterEach(() => {+ vi.useRealTimers()+ })++ it('accepts a valid signature', () => {+ const timestamp = Math.floor(Date.now() / 1000)+ const signature = sign(payload, secret, timestamp)++ expect(verifyWebhookSignature(payload, signature, String(timestamp), secret)).toBe(true)+ })++ it('rejects an invalid signature', () => {+ const timestamp = Math.floor(Date.now() / 1000)++ expect(verifyWebhookSignature(payload, 'invalid_signature', String(timestamp), secret)).toBe(false)+ })++ it('rejects a wrong secret', () => {+ const timestamp = Math.floor(Date.now() / 1000)+ const signature = sign(payload, 'wrong_secret', timestamp)++ expect(verifyWebhookSignature(payload, signature, String(timestamp), secret)).toBe(false)+ })++ it('rejects a tampered payload', () => {+ const timestamp = Math.floor(Date.now() / 1000)+ const signature = sign(payload, secret, timestamp)+ const tampered = payload.replace('order.completed', 'order.canceled')++ expect(verifyWebhookSignature(tampered, signature, String(timestamp), secret)).toBe(false)+ })++ it('rejects a timestamp older than tolerance', () => {+ const oldTimestamp = Math.floor(Date.now() / 1000) - 600 // 10 minutes ago+ const signature = sign(payload, secret, oldTimestamp)++ expect(verifyWebhookSignature(payload, signature, String(oldTimestamp), secret)).toBe(false)+ })++ it('accepts a timestamp within tolerance', () => {+ const recentTimestamp = Math.floor(Date.now() / 1000) - 200 // 200 seconds ago+ const signature = sign(payload, secret, recentTimestamp)++ expect(verifyWebhookSignature(payload, signature, String(recentTimestamp), secret)).toBe(true)+ })++ it('accepts a custom tolerance', () => {+ const oldTimestamp = Math.floor(Date.now() / 1000) - 600 // 10 minutes ago+ const signature = sign(payload, secret, oldTimestamp)++ // Default 300s tolerance rejects it+ expect(verifyWebhookSignature(payload, signature, String(oldTimestamp), secret, 300)).toBe(false)+ // Custom 900s tolerance accepts it+ expect(verifyWebhookSignature(payload, signature, String(oldTimestamp), secret, 900)).toBe(true)+ })++ it('rejects a non-numeric timestamp', () => {+ const signature = sign(payload, secret, 0)++ expect(verifyWebhookSignature(payload, signature, 'not-a-number', secret)).toBe(false)+ })++ it('rejects mismatched signature lengths', () => {+ const timestamp = Math.floor(Date.now() / 1000)++ expect(verifyWebhookSignature(payload, 'short', String(timestamp), secret)).toBe(false)+ })+})++describe('WebhookEvent type', () => {+ it('types data field generically', () => {+ interface OrderData { number: string; email: string }++ const event: WebhookEvent<OrderData> = {+ id: 'evt_123',+ name: 'order.completed',+ created_at: '2026-01-15T12:00:00Z',+ data: { number: 'R123456', email: '[email protected]' },+ metadata: { spree_version: '5.4.0' },+ }++ expect(event.data.number).toBe('R123456')+ expect(event.data.email).toBe('[email protected]')+ expect(event.name).toBe('order.completed')+ })++ it('defaults data to unknown', () => {+ const event: WebhookEvent = {+ id: 'evt_456',+ name: 'custom.event',+ created_at: '2026-01-15T12:00:00Z',+ data: { anything: 'goes' },+ metadata: { spree_version: '5.4.0' },+ }++ expect(event.id).toBe('evt_456')+ })+})diff --git a/packages/sdk/tsup.config.ts b/packages/sdk/tsup.config.tsindex 397815c56a..f4a80e3896 100644--- a/packages/sdk/tsup.config.ts+++ b/packages/sdk/tsup.config.ts@@ -5,6 +5,7 @@ export default defineConfig({index: 'src/index.ts','types/index': 'src/types/index.ts','zod/index': 'src/zod/index.ts',+ webhooks: 'src/webhooks.ts',},format: ['cjs', 'esm'],dts: { resolve: ['@spree/sdk-core'] },diff --git a/spree/emails/app/mailers/spree/customer_mailer.rb b/spree/emails/app/mailers/spree/customer_mailer.rbdeleted file mode 100644index e416b4f02d..0000000000--- a/spree/emails/app/mailers/spree/customer_mailer.rb+++ /dev/null@@ -1,33 +0,0 @@-# frozen_string_literal: true--module Spree- class CustomerMailer < BaseMailer- def password_reset_email(user_id, store_id, reset_token, redirect_url = nil)- @user = Spree.user_class.find(user_id)- @current_store = Spree::Store.find(store_id)- @reset_token = reset_token- @reset_url = build_reset_url(redirect_url, reset_token)-- subject = "#{@current_store.name} #{Spree.t('customer_mailer.password_reset_email.subject')}"- mail(- to: @user.email,- from: from_address,- subject: subject,- store_url: @current_store.storefront_url,- reply_to: reply_to_address- )- end-- private-- def build_reset_url(redirect_url, token)- return nil if redirect_url.blank?-- uri = URI.parse(redirect_url)- params = URI.decode_www_form(uri.query || '')- params << ['token', token]- uri.query = URI.encode_www_form(params)- uri.to_s- end- end-enddiff --git a/spree/emails/app/subscribers/spree/customer_email_subscriber.rb b/spree/emails/app/subscribers/spree/customer_email_subscriber.rbdeleted file mode 100644index 4a5df16527..0000000000--- a/spree/emails/app/subscribers/spree/customer_email_subscriber.rb+++ /dev/null@@ -1,38 +0,0 @@-# frozen_string_literal: true--module Spree- class CustomerEmailSubscriber < Spree::Subscriber- subscribes_to 'customer.password_reset_requested'-- def handle(event)- email = event.payload['email']- return if email.blank?-- user = Spree.user_class.find_by(email: email)- return unless user-- store = find_store(event)- return unless store- return unless store.prefers_send_consumer_transactional_emails?-- reset_token = event.payload['reset_token']- redirect_url = event.payload['redirect_url']-- CustomerMailer.password_reset_email(- user.id,- store.id,- reset_token,- redirect_url- ).deliver_later- end-- private-- def find_store(event)- store_id = event.store_id- return Spree::Store.find(store_id) if store_id.present?-- Spree::Current.store || Spree::Store.default- end- end-enddiff --git a/spree/emails/lib/spree/emails/engine.rb b/spree/emails/lib/spree/emails/engine.rbindex e30aad7a9a..cbfa7ac59f 100644--- a/spree/emails/lib/spree/emails/engine.rb+++ b/spree/emails/lib/spree/emails/engine.rb@@ -15,8 +15,7 @@ module SpreeSpree::OrderEmailSubscriber,Spree::ShipmentEmailSubscriber,Spree::ReimbursementEmailSubscriber,- Spree::NewsletterSubscriberEmailSubscriber,- Spree::CustomerEmailSubscriber+ Spree::NewsletterSubscriberEmailSubscriber]endenddiff --git a/spree/emails/spec/mailers/spree/customer_mailer_spec.rb b/spree/emails/spec/mailers/spree/customer_mailer_spec.rbdeleted file mode 100644index 0ae42250df..0000000000--- a/spree/emails/spec/mailers/spree/customer_mailer_spec.rb+++ /dev/null@@ -1,92 +0,0 @@-require 'spec_helper'-require 'email_spec'--describe Spree::CustomerMailer, type: :mailer do- include EmailSpec::Helpers- include EmailSpec::Matchers-- let!(:store) { @default_store }- let(:user) { create(:user, email: '[email protected]', first_name: 'Jane') }- let(:reset_token) { 'test-reset-token-123' }- let(:redirect_url) { 'https://mystore.com/reset-password' }-- describe '#password_reset_email' do- context 'with redirect_url' do- let(:email) { described_class.password_reset_email(user.id, store.id, reset_token, redirect_url) }-- it 'sends to the correct email address' do- expect(email.to).to eq(['[email protected]'])- end-- it 'has correct subject with store name' do- expect(email.subject).to eq("#{store.name} Password Reset")- end-- it 'uses store from_address' do- expect(email.from).to eq([store.mail_from_address])- end-- it 'uses store reply_to address' do- expect(email.reply_to).to eq([store.mail_from_address])- end-- it 'includes reset URL with token' do- expect(email).to have_body_text('https://mystore.com/reset-password?token=test-reset-token-123')- end-- it 'includes the Reset Password button text' do- expect(email).to have_body_text('Reset Password')- end-- it 'includes greeting with user first name' do- expect(email).to have_body_text('Hi Jane,')- end-- it 'includes store team sign-off' do- expect(email).to have_body_text("#{store.name} Team")- end- end-- context 'with redirect_url that has existing query params' do- let(:redirect_url_with_params) { 'https://mystore.com/reset-password?locale=en' }- let(:email) { described_class.password_reset_email(user.id, store.id, reset_token, redirect_url_with_params) }-- it 'appends token to existing query params' do- expect(email).to have_body_text('https://mystore.com/reset-password?locale=en&token=test-reset-token-123')- end- end-- context 'without redirect_url' do- let(:email) { described_class.password_reset_email(user.id, store.id, reset_token, nil) }-- it 'does not include a reset URL link' do- expect(email).not_to have_body_text('mystore.com/reset-password')- end-- it 'does not render the reset button' do- expect(email).not_to have_body_text('Reset Password')- end-- it 'still sends the email successfully' do- expect(email.to).to eq(['[email protected]'])- end- end-- context 'when user has no first name' do- let(:user_no_name) { create(:user, email: '[email protected]', first_name: nil) }- let(:email) { described_class.password_reset_email(user_no_name.id, store.id, reset_token, redirect_url) }-- it 'uses email in greeting' do- expect(email).to have_body_text('Hi [email protected],')- end- end-- context 'with preference :send_core_emails set to false' do- it 'sends no email' do- Spree::Config.set(:send_core_emails, false)- message = described_class.password_reset_email(user.id, store.id, reset_token, redirect_url)- expect(message.body).to be_blank- end- end- end-enddiff --git a/spree/emails/spec/subscribers/spree/customer_email_subscriber_spec.rb b/spree/emails/spec/subscribers/spree/customer_email_subscriber_spec.rbdeleted file mode 100644index c1821f0f6c..0000000000--- a/spree/emails/spec/subscribers/spree/customer_email_subscriber_spec.rb+++ /dev/null@@ -1,118 +0,0 @@-# frozen_string_literal: true--require 'spec_helper'--RSpec.describe Spree::CustomerEmailSubscriber do- let(:store) { create(:store) }- let(:user) { create(:user, email: '[email protected]') }- let(:subscriber) { described_class.new }- let(:reset_token) { 'test-reset-token-123' }- let(:redirect_url) { 'https://mystore.com/reset-password' }-- def mock_event(payload = {}, store_id: store.id)- double('Event',- payload: payload.deep_stringify_keys,- store_id: store_id- )- end-- before do- store.update!(preferences: store.preferences.merge(send_consumer_transactional_emails: true))- end-- describe 'customer.password_reset_requested event' do- let(:event) do- mock_event(- { email: user.email, reset_token: reset_token, redirect_url: redirect_url },- store_id: store.id- )- end-- it 'sends password reset email' do- expect(Spree::CustomerMailer).to receive(:password_reset_email)- .with(user.id, store.id, reset_token, redirect_url)- .and_return(double(deliver_later: true))-- subscriber.handle(event)- end-- it 'passes nil redirect_url when not in payload' do- event_without_redirect = mock_event(- { email: user.email, reset_token: reset_token },- store_id: store.id- )-- expect(Spree::CustomerMailer).to receive(:password_reset_email)- .with(user.id, store.id, reset_token, nil)- .and_return(double(deliver_later: true))-- subscriber.handle(event_without_redirect)- end-- context 'when store disables transactional emails' do- before do- store.update!(preferences: store.preferences.merge(send_consumer_transactional_emails: false))- end-- it 'does not send email' do- expect(Spree::CustomerMailer).not_to receive(:password_reset_email)-- subscriber.handle(event)- end- end-- context 'when email is blank' do- let(:event) { mock_event({ email: '', reset_token: reset_token }, store_id: store.id) }-- it 'does not send email' do- expect(Spree::CustomerMailer).not_to receive(:password_reset_email)-- subscriber.handle(event)- end- end-- context 'when email is nil' do- let(:event) { mock_event({ reset_token: reset_token }, store_id: store.id) }-- it 'does not send email' do- expect(Spree::CustomerMailer).not_to receive(:password_reset_email)-- subscriber.handle(event)- end- end-- context 'when user is not found' do- let(:event) do- mock_event(- { email: '[email protected]', reset_token: reset_token },- store_id: store.id- )- end-- it 'does not send email' do- expect(Spree::CustomerMailer).not_to receive(:password_reset_email)-- subscriber.handle(event)- end- end-- context 'when store_id is nil' do- let(:event) do- mock_event(- { email: user.email, reset_token: reset_token, redirect_url: redirect_url },- store_id: nil- )- end-- it 'falls back to current store' do- allow(Spree::Current).to receive(:store).and_return(store)-- expect(Spree::CustomerMailer).to receive(:password_reset_email)- .with(user.id, store.id, reset_token, redirect_url)- .and_return(double(deliver_later: true))-- subscriber.handle(event)- end- end- end-end