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.

6.5 KB
Raw Blame
// @ts-check
// POST /api/forge/webhook/tripo: Tripo reporting a text-to-model /
// image-to-model task done or failed. Polling (pollJob in api/forge.js)
// stays the fallback when no webhook arrives in time or TRIPO_WEBHOOK_SECRET
// is unset; this endpoint only completes a job faster when it does.
//
// Same three properties as api/print/webhook/[provider].js, in the same
// order:
//
//   1. AUTHENTICITY. Tripo-Webhook-Signature is `t=<unix>,v1=<hex>`, an
//      HMAC-SHA256 of `{timestamp}.{raw body}` keyed on TRIPO_WEBHOOK_SECRET,
//      constant-time compared, with a 5 minute replay window. Unverified or
//      unconfigured (no secret set) never reaches JSON.parse.
//   2. IDEMPOTENCY. Tripo-Webhook-Delivery is claimed on forge_webhook_deliveries
//      before the payload's meaning is used, so a retried delivery is a 200
//      no-op.
//   3. ORDERING. materializeCreation is already idempotent on job status (a
//      second completion for a 'done' row returns its durable copy without
//      re-writing it), so an out-of-order or duplicate task.completed can
//      never regress a row that a prior poll already finished.
//
// Deliberately minimal completion, not pollJob's full richness (quality-gate
// scoring, result-cache population, failover redispatch): the webhook's job
// is to materialize or fail the row fast. A client still polling after the
// webhook lands sees the same 'done'/'failed' row and gets the full
// pollJob response on its next poll.

import { createHmac, timingSafeEqual } from 'node:crypto';
import { error, json, method, readBody, wrap } from '../../_lib/http.js';
import {
	claimForgeWebhookDelivery,
	findByJobAnyClient,
	forgeStoreEnabled,
	markFailed,
	markForgeWebhookApplied,
	materializeCreation,
	releaseForgeWebhookDelivery,
} from '../../_lib/forge-store.js';

const PROVIDER = 'tripo';
const MAX_BODY_BYTES = 256 * 1024;
const REPLAY_WINDOW_SECONDS = 300;

/**
 * @param {string} rawBody
 * @param {Record<string, string | string[] | undefined>} headers
 * @returns {{ ok: boolean, reason?: string }}
 */
export function verifySignature(rawBody, headers) {
	const secret = process.env.TRIPO_WEBHOOK_SECRET || '';
	if (!secret) return { ok: false, reason: 'webhook not configured (TRIPO_WEBHOOK_SECRET unset)' };

	const header = headers?.['tripo-webhook-signature'];
	const value = Array.isArray(header) ? header[0] : header;
	const m = /^t=(\d+),v1=([0-9a-f]+)$/i.exec(String(value || '').trim());
	if (!m) return { ok: false, reason: 'missing or malformed Tripo-Webhook-Signature' };

	const timestamp = Number(m[1]);
	const sig = m[2].toLowerCase();
	if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > REPLAY_WINDOW_SECONDS) {
		return { ok: false, reason: 'signature timestamp outside the replay window' };
	}

	const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
	const a = Buffer.from(sig, 'utf8');
	const b = Buffer.from(expected, 'utf8');
	if (a.length !== b.length || !timingSafeEqual(a, b)) {
		return { ok: false, reason: 'signature mismatch' };
	}
	return { ok: true };
}

/** Tripo's error.message (task.failed) or a generic note. */
function failureMessage(data) {
	const msg = data?.error?.message || data?.error?.code;
	return msg ? String(msg).slice(0, 500) : 'tripo task failed';
}

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

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

	if (!forgeStoreEnabled()) {
		// 503 so Tripo retries: the delivery is genuine, we just cannot record it.
		return error(res, 503, 'not_configured', 'forge webhooks need a configured database');
	}

	const deliveryHeader = req.headers?.['tripo-webhook-delivery'];
	const deliveryId = String(Array.isArray(deliveryHeader) ? deliveryHeader[0] : deliveryHeader || '').trim();
	if (!deliveryId) {
		return error(res, 400, 'validation_error', 'missing Tripo-Webhook-Delivery header');
	}

	// Claim before parsing the body's meaning: the claim is what makes a retry
	// harmless, and it must happen even for a payload that turns out malformed,
	// an event type we end up ignoring (balance.low), or a task we cannot find a
	// row for. job_id is filled in below once it's known; a claim racing ahead
	// of that fill is still a correct, singular claim on (provider, delivery_id).
	const { fresh } = await claimForgeWebhookDelivery({ provider: PROVIDER, deliveryId, jobId: null });
	if (!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');
	}

	const eventType = String(payload?.type || '').trim();
	const data = payload?.data || {};
	const taskId = String(data?.task_id || '').trim();
	if (!taskId) {
		return error(res, 400, 'validation_error', 'body carries no data.task_id');
	}

	if (eventType !== 'task.completed' && eventType !== 'task.failed') {
		// balance.low and anything future: acknowledged, not applied to a job.
		return json(res, 200, { ok: true, applied: false, reason: `event '${eventType}' is informational` });
	}

	// The claim above is released if the lookup or the apply throws, so the 5xx
	// makes Tripo's retry run the side effect again instead of hitting the ledger.
	let applied = true;
	let status;
	try {
		const existing = await findByJobAnyClient({ replicateJobId: taskId });
		if (!existing) {
			// Verified sender, unknown job (e.g. a task submitted before this row's
			// retention window, or outside forge entirely). Answer 200 so Tripo stops
			// retrying.
			return json(res, 200, { ok: true, applied: false, reason: 'no matching job' });
		}
		status = existing.status;
		if (eventType === 'task.completed') {
			const modelUrl = data?.output?.model_url;
			if (!modelUrl) {
				applied = false;
			} else {
				const result = await materializeCreation({
					replicateJobId: taskId,
					clientKey: existing.client_key,
					glbUrl: modelUrl,
				});
				status = result ? 'done' : existing.status;
				applied = Boolean(result);
			}
		} else {
			await markFailed({ replicateJobId: taskId, clientKey: existing.client_key, error: failureMessage(data) });
			status = 'failed';
		}
		await markForgeWebhookApplied({ provider: PROVIDER, deliveryId });
	} catch (err) {
		await releaseForgeWebhookDelivery({ provider: PROVIDER, deliveryId }).catch(() => {});
		throw err;
	}

	return json(res, 200, { ok: true, applied, status });
});