Webhooks

Overview

Instead of polling for order status, you can configure Henry to push events directly to your server via webhooks. When an order transitions state - placed, completed, cancelled - Henry fires an HTTP POST to your endpoint with a signed payload. Webhooks are configured per-cart via the settings.events array on cart.create.

How it works

1. Register a webhook endpoint

Go to the Henry Dashboard, open your app settings, and add a webhook endpoint URL. Henry will generate a webhook UUID and a webhook secret for that endpoint.

The UUID is used in cart settings to reference the webhook
The secret is used to verify incoming requests (keep it private, like an API key)

2. Configure a cart with webhook events

Pass the webhook UUID in settings.events when creating a cart. Henry fires that webhook when the specified event occurs.

const cart = await henry.cart.create({
	items: [
		{
			link: 'https://www.petbarn.com.au/p/love-em-air-dried-beef-liver-dog-treat/139654',
			quantity: 1,
		},
	],
	settings: {
		events: [
			{
				type: 'order.purchase', // fire for any update to the purchase
				data: [
					{
						type: 'send_webhook',
						webhookUUID: 'c5dbd16b-60f1-42c7-8d36-a55c46e7a8c6',
					},
				],
			},
		],
	},
});

const { checkoutUrl } = cart.data;

To fire on specific outcomes, use a more granular event type:

settings: {
  events: [
    {
      type: 'order.purchase.complete',   // only on a completed purchase
      data: [{ type: 'send_webhook', webhookUUID: '...' }],
    },
    {
      type: 'order.purchase.cancelled',  // only on a cancelled purchase
      data: [{ type: 'send_webhook', webhookUUID: '...' }],
    },
  ],
}

3. Receive and verify the webhook

Henry sends a POST request with three important headers:

Header	Description
`X-Henry-Signature`	HMAC-SHA256 hex signature of `{timestamp}.{body}`
`X-Henry-Timestamp`	Unix timestamp in milliseconds
`Content-Type`	`application/json`

Always verify the signature before processing the payload.

Verification logic

import { createHmac, timingSafeEqual } from 'crypto';

const WEBHOOK_SECRET = process.env.HENRY_WEBHOOK_SECRET!;
const REPLAY_WINDOW_MS = 5 * 60 * 1000; // 5 minutes

function verifyHenryWebhook(rawBody: string, signature: string | null, timestamp: string | null): boolean {
	if (!signature || !timestamp) return false;

	const ts = Number(timestamp);

	// Reject stale requests (replay attack prevention)
	if (Math.abs(Date.now() - ts) > REPLAY_WINDOW_MS) return false;

	// Reconstruct the signed payload
	const signedPayload = `${ts}.${rawBody}`;

	// Constant-time comparison to prevent timing attacks
	const expected = createHmac('sha256', WEBHOOK_SECRET).update(signedPayload).digest();
	const actual = Buffer.from(signature, 'hex');
	return expected.byteLength === actual.byteLength && timingSafeEqual(expected, actual);
}

Always read the raw request body before parsing it as JSON. Parsing first can change the string representation and break signature verification.

Full server example (Node.js / Express)

import express from 'express';
import { createHmac } from 'crypto';

const app = express();
const WEBHOOK_SECRET = process.env.HENRY_WEBHOOK_SECRET!;

// Use raw body parser for the webhook route
app.post('/webhook/henry', express.raw({ type: 'application/json' }), (req, res) => {
	const rawBody = req.body.toString('utf8');
	const signature = req.headers['x-henry-signature'] as string;
	const timestamp = req.headers['x-henry-timestamp'] as string;

	if (!verifyHenryWebhook(rawBody, signature, timestamp)) {
		return res.status(401).send('Unauthorized');
	}

	let event: HenryWebhookPayload;
	try {
		event = JSON.parse(rawBody);
	} catch {
		return res.status(400).send('Invalid JSON');
	}

	// Always respond 200 quickly - process async
	res.json({ received: true });
	handleEvent(event).catch(console.error);
});

async function handleEvent(event: HenryWebhookPayload) {
	console.log(`[${event.timestamp}] ${event.event}`, event.data);

	switch (event.event) {
		case 'order.purchase.full.complete':
			await fulfillOrder(event.data);
			break;
		case 'order.purchase.full.cancelled':
			await notifyUserOfCancellation(event.data);
			break;
	}
}

Full server example (Bun)

import { timingSafeEqual } from 'crypto';

const WEBHOOK_SECRET = process.env.HENRY_WEBHOOK_SECRET ?? '';
const REPLAY_WINDOW_MS = 5 * 60 * 1000;

function verifySignature(body: string, signature: string | null, timestamp: string | null): boolean {
	if (!WEBHOOK_SECRET) return true; // skip in dev if no secret set
	if (!signature || !timestamp) return false;

	const ts = Number(timestamp);
	if (Math.abs(Date.now() - ts) > REPLAY_WINDOW_MS) return false;

	const signedPayload = `${ts}.${body}`;
	const hasher = new Bun.CryptoHasher('sha256', WEBHOOK_SECRET);
	hasher.update(signedPayload);
	const expected = Buffer.from(hasher.digest('hex'), 'hex');
	const actual = Buffer.from(signature, 'hex');
	return expected.byteLength === actual.byteLength && timingSafeEqual(expected, actual);
}

Bun.serve({
	port: 6789,
	async fetch(req) {
		const url = new URL(req.url);

		if (url.pathname === '/webhook' && req.method === 'POST') {
			const body = await req.text();
			const signature = req.headers.get('x-henry-signature');
			const timestamp = req.headers.get('x-henry-timestamp');

			if (!verifySignature(body, signature, timestamp)) {
				return new Response('Unauthorized', { status: 401 });
			}

			let event: HenryWebhookPayload;
			try {
				event = JSON.parse(body);
			} catch {
				return new Response('Invalid JSON', { status: 400 });
			}

			// Respond immediately, process async
			handleEvent(event).catch(console.error);
			return Response.json({ received: true });
		}

		return new Response('Not Found', { status: 404 });
	},
});

Webhook payload structure

Henry sends a consistent envelope for all events:

type HenryWebhookPayload = {
	event: string; // e.g. "order.purchase"
	timestamp: string; // ISO 8601
	data: OrderEventData | PointsEventData | TierEventData;
};

Example payload

{
	"event": "order.purchase.full.complete",
	"timestamp": "2025-03-17T14:32:00.000Z",
	"data": {
		"status": "complete",
		"orderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
		"cartId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		"items": [
			{
				"status": "complete",
				"quantity": 1,
				"productLink": "https://www.nike.com/t/air-max-270-shoes/AH8050-002",
				"productRawUrl": "https://www.nike.com/t/air-max-270-shoes/AH8050-002",
				"merchantName": "Nike",
				"variant": { "size": "10", "color": "Black" },
				"metadata": { "source": "homepage" }
			}
		],
		"details": {
			"name": { "firstName": "Jane", "lastName": "Doe" },
			"email": "jane@example.com"
		},
		"results": {
			"costs": {
				"subtotal": { "value": 150.00, "currency": "USD" },
				"serviceFee": { "value": 7.50, "currency": "USD" },
				"total": { "value": 157.50, "currency": "USD" }
			}
		}
	}
}

Event types reference

Events follow a dot-notation hierarchy. Subscribing to a parent event fires for all child events.

Order events

order.purchase.full vs order.purchase: a full purchase means every item in the cart was attempted together. A non-full purchase (e.g. order.purchase.complete) covers any purchase outcome regardless of whether it was full or partial.

Event type	Fires when
`order`	Any order event
`order.purchase`	Any purchase event (full or partial, any outcome)
`order.purchase.pending`	Purchase created, awaiting payment confirmation
`order.purchase.processing`	Payment confirmed, placing with merchants
`order.purchase.complete`	Purchase completed (full or partial)
`order.purchase.cancelled`	Purchase cancelled (full or partial)
`order.purchase.full`	A full purchase resolves to any outcome
`order.purchase.full.pending`	Full purchase pending payment confirmation
`order.purchase.full.processing`	Full purchase confirmed, placing with merchants
`order.purchase.full.complete`	All items placed successfully
`order.purchase.full.cancelled`	Full purchase cancelled (payment or merchant failure)
`order.purchase.partial`	A partial purchase resolves to any outcome
`order.purchase.partial.pending`	Partial purchase pending
`order.purchase.partial.processing`	Partial purchase processing
`order.purchase.partial.complete`	Partial purchase completed
`order.purchase.partial.cancelled`	Partial purchase cancelled
`order.item`	Any item-level event
`order.item.pending`	Individual item pending
`order.item.processing`	Individual item processing
`order.item.complete`	Individual item placed successfully
`order.item.failed`	Individual item failed
`order.update`	Any order update event
`order.update.3ds-required`	3DS authentication required
`order.update.adding-to-cart`	Adding item to merchant cart
`order.update.filling-address-details`	Filling in address details
`order.update.filling-card-details`	Filling in card details
`order.update.submitting-order`	Submitting the order
`order.update.changing-quantity`	Changing item quantity
`order.update.applying-coupon`	Applying a coupon code
`order.update.selecting-shipping`	Selecting shipping option
`order.update.selecting-options`	Selecting product options

Points & tier events

Event type	Fires when
`points`	Any points event
`points.give`	Points awarded to a buyer
`points.remove`	Points removed from a buyer
`tier`	Any tier event
`tier.give`	A tier assigned to a buyer
`tier.remove`	A tier removed from a buyer

For most use cases, subscribe to order.purchase.full.complete and order.purchase.full.cancelled - this covers both success and failure for a standard checkout.

Conditionals

Each event in settings.events accepts an optional conditional that filters when the trigger fires. Two types are supported:

settings: {
  events: [
    {
      type: 'order.purchase.full.complete',
      conditional: {
        type: 'tier',
        operator: 'equals',   // 'equals' | 'not_equals'
        value: 'your-tier-uuid',
      },
      data: [{ type: 'send_webhook', webhookUUID: '...' }],
    },
    {
      type: 'points.give',
      conditional: {
        type: 'points',
        operator: 'greater_than_or_equal',  // 'equals' | 'not_equals' | 'greater_than' | 'less_than' | 'greater_than_or_equal' | 'less_than_or_equal'
        value: 100,
      },
      data: [{ type: 'send_webhook', webhookUUID: '...' }],
    },
  ],
}

Getting Started

Key Features

Async & Events

Agents

Info

Overview

How it works

1. Register a webhook endpoint

2. Configure a cart with webhook events

3. Receive and verify the webhook

Verification logic

Full server example (Node.js / Express)

Full server example (Bun)

Webhook payload structure

Example payload

Event types reference

Order events

Points & tier events

Conditionals

Next steps

Polling

Universal Cart

​Overview

​How it works

​1. Register a webhook endpoint

​2. Configure a cart with webhook events

​3. Receive and verify the webhook

​Verification logic

​Full server example (Node.js / Express)

​Full server example (Bun)

​Webhook payload structure

​Example payload

​Event types reference

​Order events

​Points & tier events

​Conditionals

​Next steps

Polling

Universal Cart

Overview

How it works

1. Register a webhook endpoint

2. Configure a cart with webhook events

3. Receive and verify the webhook

Verification logic

Full server example (Node.js / Express)

Full server example (Bun)

Webhook payload structure

Example payload

Event types reference

Order events

Points & tier events

Conditionals

Next steps