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
import { createHmac, timingSafeEqual } from 'node:crypto'
import type { WebhookEventMap } from './generated/events'
// ─── 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 ─────────────────────────────────────────────────────
export type { WebhookEventMap, WebhookRecordReference } from './generated/events'
/** The name of every webhook event Spree publishes, plus any an extension declared. */
export type WebhookEventName = Extract<keyof WebhookEventMap, string>
/**
* Spree webhook event envelope.
*
* `data` is the record the event carries, serialized with the same Store API
* serializers as the REST API. Without a type argument this is a union over
* every event, so checking `event.name` narrows `event.data`. Pass event names
* to narrow it up front: `WebhookEvent<'order.placed' | 'order.canceled'>`.
*
* Passing a data type instead (`WebhookEvent<Order>`) still works, but is
* deprecated — it types `data` without checking it matches the event.
*
* @example
* ```ts
* import type { WebhookEvent } from '@spree/sdk/webhooks'
*
* function handle(event: WebhookEvent) {
* if (event.name === 'order.placed') {
* event.data.number // typed as Order
* }
* }
* ```
*/
export type WebhookEvent<T = WebhookEventName> = T extends WebhookEventName
? WebhookEventEnvelope<T, WebhookEventMap[T]>
: WebhookEventEnvelope<string, T>
interface WebhookEventEnvelope<Name extends string, Data> {
id: string
name: Name
created_at: string
data: Data
metadata: WebhookEventMetadata
}
/** Facts about the event itself, alongside the record in `data`. */
export interface WebhookEventMetadata {
spree_version: string
[key: string]: unknown
}
// ─── Construction ──────────────────────────────────────────────
/** Anything with a `parse` method that throws on invalid data, such as a Zod schema. */
export interface WebhookDataSchema {
parse(data: unknown): unknown
}
export interface ConstructWebhookEventOptions {
/** Max age of the timestamp in seconds (default: 300 = 5 min). */
toleranceSeconds?: number
/**
* Schemas to validate `data` with, keyed by event name — pass
* `webhookEventSchemas` from `@spree/sdk/zod`. A schema that rejects `data`
* throws its own error; `data` itself is returned as received. An event
* without a schema is returned unvalidated.
*/
schemas?: Partial<Record<string, WebhookDataSchema>>
}
/** Raised by {@link constructWebhookEvent} when a request is not a genuine Spree webhook. */
export class WebhookVerificationError extends Error {
constructor(message: string) {
super(message)
this.name = 'WebhookVerificationError'
}
}
type WebhookHeaders = Headers | Record<string, string | string[] | undefined>
function readHeader(headers: WebhookHeaders, name: string): string | undefined {
if (typeof (headers as Headers).get === 'function') {
return (headers as Headers).get(name) ?? undefined
}
const record = headers as Record<string, string | string[] | undefined>
const key = Object.keys(record).find((candidate) => candidate.toLowerCase() === name)
const value = key ? record[key] : undefined
return Array.isArray(value) ? value[0] : value
}
/**
* Verifies a webhook request's signature and returns its typed event.
*
* @param rawBody - The request body exactly as received, before any JSON parsing
* @param headers - The request headers (a Fetch `Headers` or a Node headers object)
* @param secret - The webhook endpoint's secret key
* @throws {WebhookVerificationError} when the signature is missing, wrong or expired
*
* @example
* ```ts
* import { constructWebhookEvent } from '@spree/sdk/webhooks'
* import { webhookEventSchemas } from '@spree/sdk/zod'
*
* const event = constructWebhookEvent(rawBody, request.headers, process.env.SPREE_WEBHOOK_SECRET, {
* schemas: webhookEventSchemas,
* })
*
* switch (event.name) {
* case 'order.placed':
* await fulfil(event.data) // Order
* break
* case 'customer.password_reset_requested':
* await sendResetEmail(event.data.email, event.data.reset_token)
* break
* }
* ```
*/
export function constructWebhookEvent(
rawBody: string,
headers: WebhookHeaders,
secret: string,
options: ConstructWebhookEventOptions = {},
): WebhookEvent {
const signature = readHeader(headers, 'x-spree-webhook-signature')
const timestamp = readHeader(headers, 'x-spree-webhook-timestamp')
if (!signature || !timestamp) {
throw new WebhookVerificationError(
'Missing X-Spree-Webhook-Signature or X-Spree-Webhook-Timestamp header',
)
}
if (!verifyWebhookSignature(rawBody, signature, timestamp, secret, options.toleranceSeconds)) {
throw new WebhookVerificationError('Webhook signature is invalid or the timestamp is too old')
}
const event = JSON.parse(rawBody) as WebhookEvent
// Validated, not replaced: a schema's parse drops fields it does not list,
// which would silently strip what a customized serializer adds.
options.schemas?.[event.name]?.parse(event.data)
return event
}