Cómo conectar tu SaaS a una red de afiliados: webhooks y firma HMAC

La idea general

Una red de afiliados necesita saber tres cosas de tu producto: de quién vino cada cuenta, en qué plan está y cuándo pagó. Para eso tu sistema y la plataforma se hablan en los dos sentidos: vos le avisás eventos (altas, cambios de plan) y ella te avisa los suyos (un pago confirmado, una cuenta que dejó de pagar).

El detalle exacto de cada endpoint está en la documentación de la API v1; acá explicamos el porqué de cada pieza para que la integración tenga sentido y no sea una lista de pasos.

1. Guardar el identificador del referido

Cuando un cliente llega desde el link de un afiliado, la URL trae un identificador de la visita como parámetro. Tu formulario de registro tiene que leerlo y guardarlo en una columna de la cuenta que se crea. Es lo que ata para siempre ese cliente a quien lo trajo.

• Guardalo al crear la cuenta, no en una cookie: tiene que sobrevivir meses.
• Usá un nombre de parámetro propio de la red, para no chocar con un programa de referidos que tu producto ya tenga.
• Si la cuenta se crea sin referido, no pasa nada: el alta se informa igual.

La lógica de fondo está en atribución de ventas en afiliados.

2. Avisar cada alta y cada cambio de plan

Justo después de crear la cuenta, desde tu servidor (nunca desde el navegador) mandás un aviso con el identificador de esa cuenta en tu sistema y, si lo hay, el referido. La llamada se autentica con una clave secreta que sólo vive en tu servidor.

Lo mismo cuando una cuenta cambia de plan: avisás el cambio. Así la plataforma sabe qué precio corresponde a cada cuenta y calcula bien la comisión.

3. El endpoint de estado

La plataforma necesita una forma de comprobar, de manera independiente, en qué plan está cada cuenta traída por un afiliado. Para eso tu sistema expone un endpoint al que se le pregunta por una cuenta y que contesta su plan actual.

Fijate en una decisión de diseño importante: el precio nunca se le pregunta al developer. El endpoint contesta qué plan tiene la cuenta; el importe sale de los precios que vos mismo publicaste en tu ficha. Así nadie tiene que confiar en un número declarado.

4. El webhook de activación

Si el cobro pasa por el catálogo, cuando un pago se confirma la plataforma te avisa para que actives el plan de esa cuenta. Es un pedido HTTP a una URL tuya, con un cuerpo JSON y un identificador de evento.

Reglas que conviene respetar:

• Verificá la firma antes de hacer nada. Si no coincide, devolvé 401 y no toques datos.
• Deduplicá por el identificador de evento. Los avisos se reintentan hasta recibir un 200, así que el mismo evento puede llegar más de una vez. Guardalo con un índice único en la misma transacción que el cambio.
• Contestá 200 aunque no puedas aplicar el evento (cuenta inexistente, plan que no vendés): reintentar no lo arregla.

Verificar la firma HMAC-SHA256

Todo lo que la plataforma te manda viene firmado con un HMAC-SHA256 del cuerpo crudo, calculado con un secreto que sólo conocen vos y ella. Comprobarlo garantiza dos cosas: que el mensaje es de quien dice ser y que nadie lo modificó en el camino.

La regla de oro: firmá y verificá el cuerpo exactamente como llega, antes de parsearlo. Si lo convertís a objeto y lo volvés a serializar, los bytes cambian y la firma no coincide.

import crypto from "node:crypto";

export function firmaValida(cuerpoCrudo, firmaRecibida) {
  const esperada = crypto
    .createHmac("sha256", process.env.SECRETO)
    .update(cuerpoCrudo)
    .digest("hex");
  const a = Buffer.from(esperada);
  const b = Buffer.from(String(firmaRecibida || ""));
  // Comparación en tiempo constante: no filtra cuántos caracteres acertó quien prueba.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Dos detalles más: comparalo con una función de tiempo constante (no con ===) y guardá el secreto en una variable de entorno, nunca en el código ni en el navegador.

Cómo probar sin riesgo

Una buena integración se prueba antes de que entre un solo cliente real. Las plataformas serias ofrecen un modo de prueba que recorre todo el camino —clave, campos, referido— sin guardar nada. Probá el alta, el cambio de plan, el endpoint de estado y el webhook con firma válida y con firma inválida.

Cuando esté lista, el paso siguiente es publicar tu producto. Y si querés entender por qué conviene hacerlo, leé cómo lograr que otros vendan tu software.