Recibir eventos en tu sistema (webhooks)

Un webhook es una dirección de tu sistema a la que Vipter llama cuando algo pasa en la tienda: una venta aprobada, un reembolso, una suscripción cancelada. Cada llamada es un POST con los datos en JSON y una firma que prueba que vino de Vipter. Esta página es para quien va a programar la recepción, o para que se la pases a esa persona.

Paso 1: agregar el endpointCopiar enlace de la sección

1. En el panel de Vipter, abre General›Integraciones›Automatizaciones›Webhooks.
2. Haz clic en Agregar endpoint.
3. Completa los campos numerados:

4. Haz clic en Crear endpoint.

Los eventos de un endpoint no se pueden editar después. Para cambiar la lista, crea un endpoint nuevo y quita el anterior.

Paso 2: guardar el secreto de firmaCopiar enlace de la sección

Justo después de crearlo, Vipter muestra Tu secreto de firma: un valor que empieza con whsec_. Guárdalo ahora. Solo se muestra una vez; puedes rotarlo después.

Copia el secreto y guárdalo en tu sistema, por ejemplo en una variable de entorno. Después de cerrar la ventana, el endpoint solo muestra el final del secreto.

Paso 3: verificar la firmaCopiar enlace de la sección

Cada llamada trae estos encabezados:

La firma es un HMAC SHA-256, en hexadecimal, calculado con tu secreto sobre el texto <t>.<cuerpo>: el valor de t, un punto y el cuerpo de la solicitud exactamente como llegó. Para comprobarla:

1. Lee el cuerpo sin procesar, antes de cualquier conversión a JSON. Un cuerpo reformateado genera otra firma.
2. Recalcula el HMAC con tu secreto y compáralo con cada v1= del encabezado. Basta con que uno coincida.
3. Rechaza las llamadas con un t demasiado antiguo. El ejemplo de abajo acepta hasta 5 minutos de diferencia.

El mismo código aparece en el panel, en Fragmento de verificación (Node.js):

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyVipterSignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return header.split(',').filter((p) => p.startsWith('v1=')).some((p) => {
    const given = Buffer.from(p.slice(3), 'hex');
    return given.length === expected.length / 2 && timingSafeEqual(given, Buffer.from(expected, 'hex'));
  });
}

Un ejemplo con Express, que recibe el cuerpo sin procesar y responde enseguida:

import express from 'express';

const app = express();

app.post('/webhooks/vipter', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8');
  if (!verifyVipterSignature(raw, req.get('Vipter-Signature') ?? '', process.env.VIPTER_WEBHOOK_SECRET)) {
    return res.status(400).send('firma inválida');
  }
  const event = JSON.parse(raw);
  // Guarda event.id e ignóralo si ya se procesó.
  res.sendStatus(200);
  // Procesa event.type y event.data.object después de responder.
});

Paso 4: enviar un evento de pruebaCopiar enlace de la sección

1. Con el endpoint activo, haz clic en Enviar evento de prueba, arriba en la página.
2. Aparece Evento de prueba en cola. y la entrega aparece en Entregas recientes.

La prueba es un evento customer.created con un cliente ficticio y "test": true dentro de data.object. Solo llega a los endpoints activos que reciben customer.created o todos los eventos.

El formato de los eventosCopiar enlace de la sección

Todos los eventos tienen el mismo sobre. El objeto en data.object depende del tipo.

{
  "id": "evt_4f1c2a9b0d3e5f6a7b8c9d0e",
  "object": "event",
  "type": "order.paid",
  "created": 1790000000,
  "livemode": true,
  "api_version": "2026-09-01",
  "data": {
    "object": {
      "object": "order",
      "id": "…",
      "status": "…",
      "total_amount": 19700,
      "currency": "BRL"
    }
  }
}

• id es único por evento. Úsalo para ignorar repeticiones: una entrega reenviada llega con el mismo id.
• Los montos de dinero vienen en centavos, como 19700 para R$ 197,00.
• Pedido ("object": "order"): id, customer_id, customer_email, subscription_id, status, total_amount, currency, refunded_amount, order_type, recurrence, offer_id, payment_method, provider_slug, paid_at, items, external_order_id, status_source, created_at, updated_at. En order.paid, también downloads, con los enlaces de descarga del comprador cuando el producto tiene archivos.
• Suscripción ("object": "subscription"): id, customer_id, customer_email, customer_name, status, current_offer_id, offer_name, product_id, product_name, billing_cycle, currency, current_amount, current_period_start, current_period_end, next_billing_at, trial_start, trial_end, cycles_completed, cycle_limit, cancel_at_period_end, cancelled_at, cancellation_reason, payment_instrument_id, created_at, updated_at.
• Cliente ("object": "customer"): id, email, name, phone, document_type, metadata, created_at, updated_at.
• Checkout abandonado ("object": "checkout_abandonment"): el comprador (customer), la oferta, el producto, la cantidad y el monto.

Lista de eventosCopiar enlace de la sección

Entregas y reintentosCopiar enlace de la sección

Una entrega funciona cuando tu sistema responde con un código 2xx en hasta 10 segundos. Cualquier otra respuesta, incluidas las redirecciones, o la falta de respuesta cuenta como fallo.

Después de un fallo, Vipter lo intenta de nuevo, hasta 8 intentos en total. La espera entre ellos es de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 24 horas y 48 horas. Después del octavo intento, la entrega queda con el estado exhausted.

En Entregas recientes, cada fila muestra el Evento, el Estado con el código HTTP y el error, los Intentos y el Último intento. Las entregas que no funcionaron tienen el botón Reenviar, que reinicia los intentos desde cero.

Mientras un endpoint está desactivado, los eventos nuevos no se guardan para él. Usa la lista de pedidos y de suscripciones del panel para revisar qué pasó en ese período.

Rotar el secreto o quitar el endpointCopiar enlace de la sección

• Rotar secreto: genera un secreto nuevo y lo muestra una sola vez. ¿Rotar el secreto? El anterior sigue válido por 24 horas. En ese período, cada llamada trae las dos firmas, y tu sistema puede cambiar el secreto sin perder eventos.
• Quitar: ¿Quitar este endpoint y su historial de entregas?

Problemas comunesCopiar enlace de la sección

• Ingresa una URL https://

  La dirección no empieza con https:// o tiene un error de escritura. No se aceptan direcciones http://.

• La firma nunca coincide

  El cuerpo se convirtió a JSON antes de la verificación, o el secreto es de otro endpoint. Verifica el cuerpo sin procesar y revisa el final del secreto en la tarjeta del endpoint.

• Las entregas fallan con timeout

  Tu sistema tarda más de 10 segundos en responder. Responde 200 en cuanto valides la firma y procesa el evento después.

• El botón de prueba está deshabilitado

  No hay ningún endpoint activo. Enciende el interruptor Activo de un endpoint.

Qué hacer despuésCopiar enlace de la sección

• Para enviar las ventas a una plataforma de anuncios en lugar de a tu sistema, consulta cómo funciona el seguimiento de conversiones.
• Conecta un área de miembros lista, como MemberKit, sin programar.