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', // every purchase event, legacy ones included
				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',   // every item was purchased
      data: [{ type: 'send_webhook', webhookUUID: '...' }],
    },
    {
      type: 'order.purchase.partially_complete',  // some items were purchased
      data: [{ type: 'send_webhook', webhookUUID: '...' }],
    },
    {
      type: 'order.purchase.failed',     // nothing was purchased
      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.complete':
		case 'order.purchase.partially_complete':
			// Placed — check data.items[].status for which items were bought
			await fulfillOrder(event.data);
			break;
		case 'order.purchase.failed':
			await notifyUserOfFailure(event.data);
			break;
	}
}

Full server example (Bun)

import { timingSafeEqual } from 'crypto';

const WEBHOOK_SECRET = process.env.HENRY_WEBHOOK_SECRET;
if (!WEBHOOK_SECRET) throw new Error('HENRY_WEBHOOK_SECRET is required');
const REPLAY_WINDOW_MS = 5 * 60 * 1000;

function verifySignature(body: string, signature: string | null, timestamp: string | null): boolean {
	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. Each delivery is a single attempt with a 10-second timeout and is not retried.

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

Example payload

{
	"event": "order.purchase.complete",
	"timestamp": "2025-03-17T14:32:00.000Z",
	"data": {
		"status": "complete",
		"orderId": "odr-ref_3fa85f64-5717-4562-b3fc",
		"cartId": "crt_sa2aEsCz9PRM",
		"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",
				"selectedOptions": ["Black", "10"],
				"metadata": { "source": "homepage" },
				"recoveryUrl": "https://www.nike.com/t/air-max-270-shoes/AH8050-002"
			}
		],
		"details": {
			"name": { "firstName": "Jane", "lastName": "Doe" },
			"email": "jane@example.com",
			"phone": "+14155550123",
			"shippingAddress": { "line1": "1 Main St", "city": "San Francisco", "province": "CA", "postalCode": "94105", "countryCode": "US" }
		},
		"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 - so order.purchase also receives the legacy full / partial events, and one settled order produces more than one delivery.

Order events

A purchase settles once and fires exactly one of order.purchase.complete (every item purchased), order.purchase.partially_complete (some items purchased) or order.purchase.failed (nothing purchased). After an item fails, the event can wait up to an hour before it fires, so it always reports the final outcome. Until then the order and that item read processing in every event payload, as they do when polled. The full and partial events are kept for existing integrations. While the purchase is pending / processing they say whether every cart item was attempted together. Once it settles they follow the outcome: complete also fires order.purchase.full.complete, partially_complete also fires order.purchase.partial.complete and order.purchase.partial.failed, and failed also fires order.purchase.full.failed.

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`	Every item was purchased
`order.purchase.partially_complete`	Some items were purchased, the rest failed
`order.purchase.failed`	No items were purchased
`order.purchase.cancelled`	Purchase cancelled
`order.purchase.full`	Legacy — see above
`order.purchase.full.pending`	Full purchase pending (legacy)
`order.purchase.full.processing`	Full purchase processing (legacy)
`order.purchase.full.complete`	Every item was purchased (legacy)
`order.purchase.full.failed`	No items were purchased (legacy)
`order.purchase.full.cancelled`	Full purchase cancelled (legacy)
`order.purchase.partial`	Legacy — see above
`order.purchase.partial.pending`	Partial purchase pending (legacy)
`order.purchase.partial.processing`	Partial purchase processing (legacy)
`order.purchase.partial.complete`	Some items were purchased (legacy)
`order.purchase.partial.failed`	Some items failed (legacy)
`order.purchase.partial.cancelled`	Partial purchase cancelled (legacy)
`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
`order.update.product-search`	Searching the merchant for the product

orderId is the same refId that cart.checkout.purchase returns. details.email, details.phone and details.shippingAddress are included only when the cart collects them. items[].recoveryUrl is a link back to the merchant for that item. On order.purchase.cancelled, results carries cancelledAt and reason instead of costs.

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.complete, order.purchase.partially_complete and order.purchase.failed directly (not a parent like order.purchase) — exactly one of them fires per purchase, once its outcome is final.

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.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