Un webhook no es una orden única ni una transacción. Es una notificación que puede llegar más de una vez, competir con otra ejecución o quedar a mitad de camino cuando un proceso falla. Si habilita un período de una suscripción, la regla de negocio debe ser clara: un mismo pago confirmado no puede otorgar dos veces el mismo beneficio.
Esta nota es una propuesta de laboratorio, no una descripción de un incidente ni de una implementación productiva existente. El contexto es el de productos SaaS que reciben notificaciones de Mercado Pago, usan Supabase Edge Functions y persisten datos en PostgreSQL.
Idea central. La Edge Function valida y normaliza. PostgreSQL decide, en una sola transacción, si el beneficio se aplica. WhatsApp se guarda como intención en una outbox para procesarse después.
Separar las identidades
Para razonar el flujo conviene distinguir:
- Notificación: el mensaje HTTP que llega.
- Recurso: el objeto que la notificación referencia.
- Pago: el cobro concreto que puede otorgar un beneficio.
- Suscripción: la relación comercial, que puede tener renovaciones.
- Beneficio: el período de acceso o efecto interno.
Una autorización de suscripción no equivale a confirmar un cobro. Tampoco conviene usar sólo el ID de la suscripción como clave de deduplicación: las renovaciones legítimas deben poder procesarse.
El fallo inicial: consultar y después escribir
La implementación ingenua recibe la notificación, consulta el pago, extiende el acceso si está aprobado y envía una confirmación. Con dos ejecuciones simultáneas, ambas pueden leer que el pago todavía no fue procesado:
La consulta previa no es una garantía. La decisión debe quedar protegida por una restricción única y una transacción que determine qué ejecución obtuvo el derecho a aplicar.
Qué significa idempotencia acá
Idempotencia no significa que cada entrega se ejecute una sola vez. Significa que repetir la misma operación comercial deja el sistema en el mismo estado: un solo beneficio para un solo pago.
- Registrar el ID de notificación sirve para diagnóstico.
- La identidad fuerte debe incluir proveedor, cuenta y pago o cobro.
- Una suscripción puede tener pagos distintos y actualizaciones legítimas.
La promesa razonable es aplicar como máximo una vez por identidad de negocio, con reintentos seguros. No es procesamiento exactamente una vez de extremo a extremo.
Autenticidad antes de tocar la base
Mercado Pago documenta Webhooks con x-signature, x-request-id y data.id. La firma se verifica con HMAC-SHA256 sobre el manifest correspondiente. Si no coincide, la función debe rechazar la petición.
Después hay que consultar el recurso al proveedor con credenciales del servidor y comprobar su relación con la cuenta, la suscripción y el negocio esperado. También corresponde validar importe, moneda y estado cuando sean reglas del producto.
Una firma válida demuestra autenticidad del mensaje, no que el beneficio sea válido para cualquier tenant. El tenant se resuelve desde asociaciones internas confiables, no desde un tenant_id enviado libremente.
Modelo de datos y transacción
create table benefit_application (
id bigserial primary key,
tenant_id uuid not null,
provider_account_id text not null,
payment_id text not null,
subscription_id uuid not null,
period_until timestamptz not null,
unique (provider_account_id, payment_id)
);
create table notification_outbox (
id bigserial primary key,
benefit_application_id bigint not null references benefit_application(id),
channel text not null,
destination text not null,
payload jsonb not null,
status text not null default 'pending',
attempts integer not null default 0,
available_at timestamptz not null default now()
);Si el modelo opera con varias cuentas del proveedor, la cuenta forma parte de la identidad única. Las recepciones pueden registrarse aparte para diagnóstico sin convertirse en la regla comercial.
En este ejemplo, p_period_until llega calculado desde la regla del producto: cada pago aprobado cubre un período fijo definido por la suscripción. Si el negocio suma días o meses, ese cálculo debe hacerse antes de llamar a la RPC y quedar explícito; greatest sólo evita retroceder el acceso, no decide por sí solo cuánto agrega cada renovación.
La base decide una sola vez
La función PostgreSQL recibe datos ya verificados y ejecuta el cambio completo dentro de una transacción:
- Insertar la aplicación con
ON CONFLICT DO NOTHING. - Comprobar si esta ejecución insertó una fila.
- Actualizar acceso sólo si obtuvo el derecho.
- Guardar la intención de WhatsApp en la outbox.
- Devolver
appliedoalready_applied.
create or replace function apply_payment_benefit(
p_tenant_id uuid,
p_provider_account_id text,
p_payment_id text,
p_subscription_id uuid,
p_period_until timestamptz,
p_whatsapp text,
p_message jsonb
)
returns text
language plpgsql
security invoker
as $$
declare
v_application_id bigint;
begin
insert into benefit_application (
tenant_id, provider_account_id, payment_id,
subscription_id, period_until
)
values (
p_tenant_id, p_provider_account_id, p_payment_id,
p_subscription_id, p_period_until
)
on conflict (provider_account_id, payment_id) do nothing
returning id into v_application_id;
if v_application_id is null then
return 'already_applied';
end if;
perform id from subscription
where id = p_subscription_id and tenant_id = p_tenant_id
for update;
if not found then
raise exception 'subscription % does not belong to tenant %', p_subscription_id, p_tenant_id;
end if;
update subscription
set access_until = greatest(coalesce(access_until, now()), p_period_until)
where id = p_subscription_id and tenant_id = p_tenant_id;
insert into notification_outbox (
benefit_application_id, channel, destination, payload
)
values (v_application_id, 'whatsapp', p_whatsapp, p_message);
return 'applied';
end;
$;El SELECT ... FOR UPDATE serializa pagos diferentes que actualizan la misma suscripción. El IF NOT FOUND evita devolver applied si la suscripción no existe o pertenece a otro tenant; la excepción provoca rollback. No reemplaza la restricción única: uno controla concurrencia sobre el acceso y la otra evita duplicar el pago.
Permisos explícitos para la RPC
SECURITY INVOKER no configura permisos por sí solo. En Supabase conviene revocar la ejecución pública, otorgarla sólo al rol que usa el backend y proteger las tablas con RLS:
revoke execute on function apply_payment_benefit(uuid, text, text, uuid, timestamptz, text, jsonb) from public, anon, authenticated;
grant execute on function apply_payment_benefit(uuid, text, text, uuid, timestamptz, text, jsonb) to service_role;
alter table benefit_application enable row level security;
alter table notification_outbox enable row level security;Los nombres de roles y las políticas deben ajustarse al despliegue. La clave service_role nunca debe exponerse al navegador; si se usa otro rol de backend, otorgale sólo la ejecución necesaria.
La Edge Function coordina
Las llamadas de red al proveedor deben quedar fuera de la transacción SQL. La Edge Function valida, consulta, normaliza y llama una sola vez a la función de base:
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2';
Deno.serve(async (request) => {
const notification = await request.json();
const verified = await verifyMercadoPagoSignature(request, notification);
if (!verified) return new Response('invalid signature', { status: 401 });
let resource;
try {
resource = await fetchMercadoPagoResource(notification);
} catch (error) {
console.error('provider_unavailable', error);
return new Response('retryable provider error', { status: 503 });
}
if (!resource) return new Response('resource unavailable', { status: 503 });
if (resource.status !== 'approved') {
return new Response('payment not approved', { status: 200 });
}
const command = normalizeApprovedPayment(resource);
const supabase = createClient(
Deno.env.get('SUPABASE_URL')!,
Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
);
const { data, error } = await supabase.rpc(
'apply_payment_benefit',
command
);
if (error) throw error;
return Response.json({ result: data }, { status: 200 });
});Ejemplo de laboratorio. Las funciones de firma, consulta y normalización son adaptadores. El payload y el recurso se deben ajustar al tópico documentado; el snippet no inventa un contrato oficial.
Si el flujo es sincrónico, la respuesta de éxito llega después del commit. Si se responde antes, primero hay que persistir una recepción durable y diseñar recuperación. No alcanza con seguir ejecutando trabajo crítico en segundo plano.
Fallos parciales y recuperación
La documentación de Mercado Pago indica que el receptor debe confirmar la recepción con HTTP 200 o 201. Si no llega esa confirmación, el proveedor puede volver a enviar la notificación; la política de reintentos debe tratarse como parte del diseño y verificarse para el tópico elegido.
| Escenario | Resultado seguro | Recuperación |
|---|---|---|
| Commit confirmado, respuesta perdida | El reintento devuelve already_applied. | Responder 200/201 y conservar la recepción. |
| Falla antes del commit | No queda beneficio parcial. | Reintentar la notificación. |
| Proveedor o base no disponible | No se confirma el beneficio. | Dejar el evento reintentable. |
| Recepción registrada, proceso interrumpido | Queda pendiente, no aplicada. | Retomar pendientes o bloqueados con un worker. |
No hay que marcar un evento como definitivamente procesado antes de aplicar el efecto comercial. Una inbox con estados necesita una política explícita de reintentos.
WhatsApp y outbox
Enviar WhatsApp dentro de la transacción no vuelve atómica una operación externa. Si el proveedor acepta el mensaje y la base hace rollback, se puede comunicar un beneficio inexistente.
La outbox guarda la intención en el mismo commit, y otro proceso la envía con reintentos. Aun así, si el proveedor acepta el mensaje y se pierde la respuesta, el reintento puede duplicarlo salvo que exista una clave idempotente externa. Una outbox no garantiza por sí sola un único envío.
Eventos desordenados
La fecha de llegada no define el orden del negocio. Hay que separar el procesamiento idempotente de cada cobro de la actualización de la suscripción. Según los datos disponibles, la estrategia puede ser serialización, versionado o reconciliación. No conviene inventar un campo de versión que la API no ofrezca.
Escenarios de prueba propuestos
La nota propone una matriz para validar el diseño, pero no incluye una suite ejecutable completa. Para convertirla en pruebas reales todavía hay que definir el esquema de subscription, los adaptadores del proveedor, los fixtures y la infraestructura de concurrencia:
- Mismo pago dos veces, secuencial y simultáneo.
- Dos pagos legítimos de la misma suscripción.
- Fallo dentro de la transacción y reintento.
- Commit exitoso con respuesta HTTP perdida.
- Firma inválida y recurso asociado a otro negocio.
- Outbox pendiente después de aplicar.
Las invariantes son una aplicación por pago, acceso correcto, una sola intención de notificación y ningún cambio parcial tras rollback. No presento resultados como ejecutados: la matriz y el código quedan listos para correr contra una base real.
Observabilidad y límites
Usaría logs estructurados con identificadores de correlación y resultados como applied, already_applied, rejected y retryable_failure. No registraría secretos, tokens, datos de tarjetas ni información personal innecesaria.
La solución garantiza que un pago no otorgue dos veces el mismo beneficio dentro de la identidad única definida y que la intención de WhatsApp quede vinculada al commit. No garantiza exactamente una entrega de red ni un único envío externo. Una reconciliación periódica complementa la idempotencia cuando hay eventos desordenados o cambios fuera del flujo normal.
Bibliografía oficial
- Mercado Pago · Notificaciones.
- Mercado Pago · Configurar notificaciones de orders.
- Supabase · Edge Functions.
- Supabase · Database Functions.
- PostgreSQL · INSERT y bloqueos explícitos.
Si estás diseñando una integración de pagos, una automatización de WhatsApp o un SaaS con suscripciones, podemos revisar el flujo y definir dónde conviene resolver cada garantía. También podés conocer mis productos y automatizaciones.