Webhooks
Eventos Toteat soportados, autenticación opcional y modelos normalizados.
Usa parseToteatWebhook para parsear payloads de webhook Toteat.
Receiver seguro
Autentica el webhook antes de persistir payloads y procesa eventos de forma idempotente.
import { parseToteatWebhook } from "@cartamatic/pos-sdk";
const webhook = parseToteatWebhook({
authentication: {
expectedSecret: process.env.CARTAMATIC_POS_TOTEAT_WEBHOOK_SECRET!,
receivedSecret: request.headers.get("x-cartamatic-webhook-secret")
},
event: "menu_changed",
payload: await request.json()
});Eventos soportados
order_status_changed
Cambios de estado o detalle de órdenes. Retorna ToteatOrderStatusChangedWebhook.
shifts_status_changed
Apertura/cierre o estado de turnos. Retorna ToteatShiftsStatusChangedWebhook.
menu_changed
Cambios de menú, productos, precios o disponibilidad. Retorna ToteatMenuChangedWebhook.
product_transfer
Transferencias multilocal de productos. Retorna ToteatProductTransferWebhook.
Por qué el evento se pasa a mano
Toteat no incluye consistentemente el nombre del evento dentro del payload. El receiver debe decidirlo por URL, route config o secreto asociado.
Autenticación
authentication es opcional porque depende de cómo se configure el receiver.
Configurar expectedSecret
Debe ser un valor no vacío y venir desde secret manager o env server-side.
Leer receivedSecret
Tómalo desde header, ruta o mecanismo acordado del receiver.
Comparar en tiempo seguro
El SDK usa timingSafeEqual y lanza PosValidationError si no coincide.
Modelos
Los webhooks con envelope comparten:
type ToteatWebhookEnvelopeBase<TEvent> = {
provider: "toteat";
event: TEvent;
ok: boolean | null;
version: string | null;
time: string | null;
restaurantId: string | null;
localNumber: string | null;
message: string | null;
raw: unknown;
};product_transfer no usa el mismo envelope completo y normaliza campos de requisición, fechas, stores e items.
Ejemplo route handler
export const POST = async (request: Request) => {
const webhook = parseToteatWebhook({
authentication: {
expectedSecret: process.env.CARTAMATIC_POS_TOTEAT_WEBHOOK_SECRET!,
receivedSecret: request.headers.get("x-cartamatic-webhook-secret")
},
event: "order_status_changed",
payload: await request.json()
});
await enqueueWebhookProcessing(webhook);
return Response.json({ ok: true });
};