Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

4.7 KB
Raw Blame
// @ts-check
// POST /api/print/webhook/:provider: a fulfillment provider reporting in.
//
// Three properties, in the order they are enforced:
//
//   1. AUTHENTICITY. The adapter verifies the delivery against the exact bytes
//      received (HMAC over the raw body, constant-time compared). An
//      unverified delivery is refused before the payload is parsed, so a
//      forged body never reaches a JSON.parse, let alone the state machine.
//      An adapter with no webhook (the manual lane) refuses everything, which
//      is why that lane has no unauthenticated door.
//   2. IDEMPOTENCY. Every serious provider retries deliveries. The claim on
//      print_webhook_deliveries is a unique-key insert, so a replay of the same
//      delivery is a no-op that returns 200 (a 4xx would make the provider
//      retry forever) and appends nothing to the timeline.
//   3. ORDERING. The state machine, not the provider, decides what may follow
//      what. A report that arrives out of order is recorded on the timeline as
//      a refused provider event and answered 200 with applied: false.
//
// The response never echoes the payload and never leaks whether an order id
// exists to an unverified caller: verification comes first.

import { error, json, method, readBody, wrap } from '../../_lib/http.js';
import {
	claimWebhookDelivery,
	getOrderByProviderId,
	markWebhookApplied,
	printStoreEnabled,
	releaseWebhookDelivery,
} from '../../_lib/print/fulfillment-queries.js';
import { getAdapter } from '../../_lib/print/adapters/index.js';
import { normalizeWebhookEvent } from '../../_lib/print/adapters/contract.js';
import { applyProviderEvent } from '../../_lib/print/fulfillment.js';

const MAX_BODY_BYTES = 256 * 1024;

export default wrap(async (req, res) => {
	if (!method(req, res, ['POST'])) return;

	const provider = String(
		req.query?.provider ?? new URL(req.url, 'http://x').pathname.split('/').pop() ?? '',
	).trim();

	const adapter = getAdapter(provider);
	if (!adapter) {
		// Unknown or unconfigured lane. 404 rather than 403: there is no endpoint
		// here to authenticate against.
		return error(res, 404, 'not_found', `no configured fulfillment provider '${provider}'`);
	}

	const raw = (await readBody(req, MAX_BODY_BYTES)).toString('utf8');
	const verdict = adapter.verifyWebhook(raw, req.headers || {});
	if (!verdict?.ok) {
		return error(res, 401, 'unauthorized', verdict?.reason || 'delivery could not be verified');
	}

	if (!printStoreEnabled()) {
		// 503 makes a provider retry, which is right: the delivery is genuine and
		// we simply cannot record it yet.
		return error(res, 503, 'not_configured', 'fulfillment webhooks need a configured database');
	}

	// Claim before parsing the body's meaning: the claim is what makes a retry
	// harmless, and it must happen even for a payload we end up not applying.
	const { fresh } = await claimWebhookDelivery({ provider, deliveryId: verdict.deliveryId });
	if (!fresh) {
		return json(res, 200, { ok: true, duplicate: true, applied: false });
	}
	// A provider-supplied delivery id is an unsigned header, so also claim the id
	// derived from the signed body: a replayed body under a new header id is
	// still the same delivery.
	if (verdict.bodyDeliveryId && verdict.bodyDeliveryId !== verdict.deliveryId) {
		const bodyClaim = await claimWebhookDelivery({ provider, deliveryId: verdict.bodyDeliveryId });
		if (!bodyClaim.fresh) {
			return json(res, 200, { ok: true, duplicate: true, applied: false });
		}
	}

	let payload;
	try {
		payload = JSON.parse(raw);
	} catch {
		return error(res, 400, 'validation_error', 'body must be JSON');
	}

	// Both claims are released if the lookup or the apply throws, so the 5xx
	// makes the provider's retry run the side effect again instead of hitting
	// the ledger and being dropped as a duplicate.
	try {
		const event = normalizeWebhookEvent(adapter.key, adapter.parseWebhook(payload));
		const order = await getOrderByProviderId(provider, event.providerOrderId);
		if (!order) {
			// Verified sender, unknown job. Answer 200 so they stop retrying, and say
			// so plainly: this is a real condition when a provider replays history
			// after we have deleted an order.
			return json(res, 200, { ok: true, applied: false, reason: 'no matching order' });
		}

		const result = await applyProviderEvent({ order, event, actor: 'provider' });
		await markWebhookApplied({ provider, deliveryId: verdict.deliveryId, orderId: order.id });

		return json(res, 200, {
			ok: true,
			applied: result.applied,
			status: result.order.status,
			reason: result.reason || undefined,
		});
	} catch (err) {
		for (const id of new Set([verdict.deliveryId, verdict.bodyDeliveryId])) {
			if (id) await releaseWebhookDelivery({ provider, deliveryId: id }).catch(() => {});
		}
		throw err;
	}
});