Webhooks de Mercado Pago con Supabase Edge Functions: verificar la firma y evitar pagos falsos
Respuesta corta: un webhook de Mercado Pago es solo un aviso. Antes de activar un plan, validá el encabezado x-signature con un HMAC-SHA256 de tu secreto y después consultá el pago en la API. Si la firma no coincide, respondé 401. Si coincide, liberá el acceso solo cuando el status sea approved. No confíes en la URL de “gracias” ni en el cuerpo de la notificación sin esa verificación.
En la guía de Checkout Pro en Lovable ya decimos que el plan se activa por webhook, no cuando el comprador vuelve a tu sitio. Esta guía se concentra en el paso que más se salta en las apps hechas con IA: verificar la firma. Sin eso, cualquiera que conozca la URL de tu función puede mandar un aviso falso y entrar como si hubiera pagado. El mismo criterio vale si cobrás con Pix: lo detallamos en Como receber Pix em um app feito no Lovable.
Paso 1: configurá la URL y guardá el secreto
En Tus integraciones, elegí la aplicación, entrá a Webhooks → Configurar notificación y cargá la URL de una Edge Function, por ejemplo https://TU-PROYECTO.supabase.co/functions/v1/webhook-mp. Revelá la clave secreta que genera Mercado Pago y guardala como secreto de Supabase (MP_WEBHOOK_SECRET), junto con el access token (MP_ACCESS_TOKEN) que vas a usar para consultar el pago. El access token no va al frontend: esa regla está en la guía de Checkout Pro.
Por defecto, las Edge Functions de Supabase exigen un JWT válido en el encabezado de autorización. Mercado Pago no envía un JWT de Supabase, así que esta función tiene que publicarse con verify_jwt = false en supabase/config.toml. Es el mismo patrón que Supabase documenta para webhooks de Stripe (configuración de funciones). La autenticidad la vas a comprobar vos, con la firma de Mercado Pago, no con un JWT.
[functions.webhook-mp]
verify_jwt = false
Las URLs que configures al crear un pago o una preferencia tienen prioridad sobre las de Tus integraciones (documentación de webhooks de Mercado Pago). Las notificaciones de Código QR no llevan firma y no deben validarse con este procedimiento.
Paso 2: validá el encabezado x-signature
Cada notificación llega con un encabezado x-signature con este formato (fuente):
x-signature: ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839
También necesitás el encabezado x-request-id y el parámetro data.id de la query de la URL. Con esos valores armás el manifiesto y calculás un HMAC-SHA256 en hexadecimal, usando tu secreto como clave:
id:<data.id>;request-id:<x-request-id>;ts:<ts>;
Si data.id viene con letras mayúsculas (pasa con algunos ids de órdenes), la documentación pide pasarlo a minúsculas antes de usarlo. Si falta data.id o x-request-id, esos tramos se sacan del manifiesto. El resultado tiene que coincidir exactamente con v1. Si no coincide, respondé 401 y no actives nada.
Los SDK oficiales traen un WebhookSignatureValidator. En una Edge Function de Supabase, que corre en Deno, lo habitual es calcularlo con la Web Crypto API:
// supabase/functions/webhook-mp/index.ts
async function hmacHex(secret, message) {
const key = await crypto.subtle.importKey(
"raw", new TextEncoder().encode(secret),
{ name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
return [...new Uint8Array(sig)].map(b => b.toString(16).padStart(2, "0")).join("");
}
function part(header, name) {
for (const p of header.split(",")) {
const [k, ...rest] = p.trim().split("=");
if (k === name) return rest.join("=");
}
return "";
}
Deno.serve(async (req) => {
const secret = Deno.env.get("MP_WEBHOOK_SECRET") ?? "";
const xSignature = req.headers.get("x-signature") ?? "";
const xRequestId = req.headers.get("x-request-id") ?? "";
let dataId = new URL(req.url).searchParams.get("data.id") ?? "";
if (/[A-Z]/.test(dataId)) dataId = dataId.toLowerCase();
const ts = part(xSignature, "ts");
const v1 = part(xSignature, "v1");
let manifest = "";
if (dataId) manifest += `id:${dataId};`;
if (xRequestId) manifest += `request-id:${xRequestId};`;
manifest += `ts:${ts};`;
const expected = await hmacHex(secret, manifest);
if (!secret || !v1 || expected !== v1) {
return new Response("unauthorized", { status: 401 });
}
// Firma válida: consultar el pago en la API y recién entonces activar el plan.
return new Response("ok", { status: 200 });
});
Paso 3: respondé 200 o 201 en menos de 22 segundos
Cuando la notificación llega, Mercado Pago espera un 200 o un 201 en un plazo de 22 segundos. Si no lo recibe, reintenta cada 15 minutos; después del tercer intento el plazo se prorroga, pero los envíos siguen (fuente). Por eso tu función tiene que ser idempotente: la misma notificación puede llegar más de una vez y también fuera de orden. El guía de webhooks del SDK oficial recomienda tratar el aviso como una señal, no como la verdad, y consultar el recurso en la API.
Paso 4: consultá el pago en la API y activá el plan solo si está approved
Con la firma ya validada, pedí el recurso con tu access token. Para un pago de Checkout Pro o de la Payments API:
GET https://api.mercadopago.com/v1/payments/{id}
Authorization: Bearer <MP_ACCESS_TOKEN>
Activá el plan del usuario solo si status es approved. Guardá el id del pago en tu base y no lo proceses dos veces. El precio y el plan tienen que estar definidos en el servidor, nunca tomados del cuerpo de la notificación ni del navegador.
Paso 5: protegé la tabla de pedidos con RLS
La Edge Function, con la clave secreta del servidor, es quien escribe el estado del pago. El usuario autenticado puede leer el suyo, no marcarse a sí mismo como “pro”. El patrón está en la guía de Checkout Pro y el detalle de las políticas, en el artículo de RLS para apps de Lovable.
Paso 6: probá antes de ir a producción
En la misma pantalla de Webhooks, Mercado Pago documenta cómo simular el recibimiento de una notificación. Hacé una compra de prueba con credenciales de test, confirmá que una firma inválida responde 401, que una válida consulta la API y que un reintento no activa el plan dos veces.
El MCP oficial de Mercado Pago
Mercado Pago publica un servidor MCP oficial para agentes de IA. Sirve para buscar la documentación sin salir del editor, configurar y monitorear webhooks, crear usuarios de prueba y medir la calidad de la integración. Está documentado para Cursor, VS Code, Windsurf, Cline, Claude y ChatGPT (resumen del MCP Server). La conexión remota usa el endpoint https://mcp.mercadopago.com/mcp (guía de conexión). El access token de tu cuenta es secreto: no lo pegues en un chat ni en un archivo del frontend.
Si pensabas usar solo Stripe
En Latinoamérica, Stripe abre cuentas locales solo en México y Brasil, según la página de disponibilidad global de Stripe (consultada el 15 de noviembre de 2026). Si tu cuenta no está en esos países, Mercado Pago con el webhook verificado es el camino habitual; comparamos opciones en ¿Stripe no está disponible en tu país?.
Antes de cobrar el primer pago, conviene escanear el repo: escaneo gratis, en el navegador, sin crear cuenta. Si querés que te avisemos cuando salga la próxima guía, el boletín de LaunchLatam es gratis.
Preguntas frecuentes
¿Puedo activar el plan cuando el usuario vuelve a /gracias?
No. Cualquiera puede abrir esa URL. La fuente de verdad es el webhook con la firma x-signature validada y, después, la consulta a la API de Mercado Pago: el plan se activa solo si el status es approved.
¿Cómo valido x-signature en una Edge Function, sin el SDK?
Extraé ts y v1 del encabezado, armá el manifiesto id:
¿Qué pasa si no respondo 200 a tiempo?
Mercado Pago espera 22 segundos. Si no recibe 200 o 201, reintenta cada 15 minutos; después del tercer intento el plazo se prorroga, pero los envíos siguen. Tu función tiene que ser idempotente para no activar el plan dos veces.
¿Querés saber cómo está tu app?
Escaneá tu repo gratis en segundos, sin crear cuenta.