Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Added supoort for webhooks in SDK and next packages

Damian Legawiecb0c2ce9abaf7
diff --git a/docker-compose.yml b/docker-compose.yml
index 9dcfa00b66..ed9d4bff93 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -17,8 +17,8 @@ x-app: &app
RAILS_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: 5s
retries: 5
- mailpit:
- image: axllent/mailpit
- ports:
- - "8025:8025"
- - "1025:1025"
-
web:
<<: *app
ports:
diff --git a/docs/developer/core-concepts/webhooks.mdx b/docs/developer/core-concepts/webhooks.mdx
index 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
```ruby
class WebhooksController < ApplicationController
@@ -209,7 +243,8 @@ class WebhooksController < ApplicationController
request.body.rewind
signature = 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)
end
diff --git a/docs/developer/storefront/nextjs/spree-next-package.mdx b/docs/developer/storefront/nextjs/spree-next-package.mdx
index 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:
```env
SPREE_API_URL=https://api.mystore.com
SPREE_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).
+
## TypeScript
All types are re-exported from `@spree/sdk`:
diff --git a/packages/next/CHANGELOG.md b/packages/next/CHANGELOG.md
index 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 Changes
diff --git a/packages/next/README.md b/packages/next/README.md
index 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 val
const 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).
+
## TypeScript
All types are re-exported from `@spree/sdk` for convenience:
diff --git a/packages/next/package.json b/packages/next/package.json
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.md
deleted file mode 100644
index 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.md
index 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 Changes
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 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
### Setup
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.rb
deleted file mode 100644
index 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
-end
diff --git a/spree/emails/app/subscribers/spree/customer_email_subscriber.rb b/spree/emails/app/subscribers/spree/customer_email_subscriber.rb
deleted file mode 100644
index 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
-end
diff --git a/spree/emails/lib/spree/emails/engine.rb b/spree/emails/lib/spree/emails/engine.rb
index e30aad7a9a..cbfa7ac59f 100644
--- a/spree/emails/lib/spree/emails/engine.rb
+++ b/spree/emails/lib/spree/emails/engine.rb
@@ -15,8 +15,7 @@ module Spree
Spree::OrderEmailSubscriber,
Spree::ShipmentEmailSubscriber,
Spree::ReimbursementEmailSubscriber,
- Spree::NewsletterSubscriberEmailSubscriber,
- Spree::CustomerEmailSubscriber
+ Spree::NewsletterSubscriberEmailSubscriber
]
end
end
diff --git a/spree/emails/spec/mailers/spree/customer_mailer_spec.rb b/spree/emails/spec/mailers/spree/customer_mailer_spec.rb
deleted file mode 100644
index 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
-end
diff --git a/spree/emails/spec/subscribers/spree/customer_email_subscriber_spec.rb b/spree/emails/spec/subscribers/spree/customer_email_subscriber_spec.rb
deleted file mode 100644
index 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