Webhooks

Fynex puede enviar notificaciones HTTP POST a tu servidor cuando ocurren eventos importantes en la plataforma. Esto te permite reaccionar en tiempo real a cambios en cuentas, pagos, promesas y más, sin necesidad de hacer polling.

Cómo funciona

1. Registrás una URL y los eventos que te interesan.
2. Cuando ocurre un evento, Fynex envía un POST con los datos a tu URL.
3. Tu servidor recibe el payload, verifica la firma y procesa el evento.

Configurar un webhook

1. Andá a Configuración > Integraciones.
2. En la sección Webhooks, hacé clic en Agregar webhook.
3. Ingresá la URL de tu endpoint (debe ser HTTPS en producción).
4. Seleccioná los eventos que querés recibir.
5. Opcionalmente, agregá una descripción.
6. Hacé clic en Crear.

Al crear el webhook, Fynex genera automáticamente un secreto HMAC que se usa para firmar cada entrega. Este secreto se muestra en la respuesta de creación vía API — guardalo de forma segura.

Eventos disponibles

Evento	Descripción
account.created	Se creó una nueva cuenta
account.updated	Se actualizaron datos de una cuenta
account.status_changed	Cambió el estado de cobranza de una cuenta
contact.created	Se creó un nuevo contacto
contact.updated	Se actualizaron datos de un contacto
interaction.completed	Se completó una interacción (llamada, email, SMS, WhatsApp)
promise.created	El deudor registró una promesa de pago
promise.fulfilled	Se cumplió una promesa de pago
promise.broken	Venció una promesa de pago sin cumplirse
payment.registered	Se registró un pago
dispute.created	El deudor disputó la deuda
escalation.created	Se creó una escalación

Formato del payload

Cada entrega incluye un JSON con esta estructura:

{
  "event_type": "payment.registered",
  "timestamp": "2026-03-22T14:30:00.000Z",
  "data": {
    "account_id": "uuid-de-la-cuenta",
    "amount": 15000,
    "currency": "ARS",
    "payment_method": "transfer"
  }
}

Los headers de la entrega incluyen:

Header	Descripción
Content-Type	application/json
X-Fynex-Signature	Firma HMAC-SHA256 del body
X-Fynex-Event	Tipo de evento (ej.: payment.registered)
X-Fynex-Delivery	ID único de esta entrega

Verificación de firma

Cada entrega viene firmada con HMAC-SHA256 usando el secreto del webhook. Siempre verificá la firma antes de procesar el evento para asegurar que proviene de Fynex.

El header X-Fynex-Signature tiene el formato sha256=<hex>.

Ejemplo en Node.js

import crypto from "crypto";

function verifySignature(body, signature, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// En tu handler:
app.post("/webhook", (req, res) => {
  const signature = req.headers["x-fynex-signature"];
  const isValid = verifySignature(
    JSON.stringify(req.body),
    signature,
    process.env.FYNEX_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  // Procesá el evento...
  res.status(200).send("OK");
});

WARNING

Usá crypto.timingSafeEqual para comparar firmas. Una comparación directa con === es vulnerable a ataques de timing.

Política de reintentos

Si tu endpoint no responde con un código 2xx, Fynex reintenta la entrega con backoff exponencial:

Intento	Retraso aproximado
1	Inmediato
2	1 minuto
3	5 minutos
4	30 minutos
5	2 horas

Después de 5 intentos fallidos, la suscripción se desactiva automáticamente. Podés reactivarla desde Configuración una vez que tu endpoint esté funcionando.

TIP

Respondé con 200 OK lo más rápido posible y procesá el evento de forma asincrónica. Si tu handler tarda más de 5 segundos, Fynex considera que la entrega falló.

Probar webhooks

Podés enviar un evento de prueba a tu endpoint para verificar que todo funciona:

1. Andá a Configuración > Integraciones > Webhooks.
2. Buscá el webhook que querés probar.
3. Hacé clic en Enviar test.

El evento de prueba tiene el tipo test.ping y no afecta ningún dato real.

Gestionar webhooks

• Pausar — Suspendé temporalmente las entregas sin eliminar la suscripción.
• Editar — Modificá la URL, eventos o descripción.
• Eliminar — Borrá la suscripción permanentemente.

Buenas prácticas

• Verificá siempre la firma — Nunca proceses un webhook sin validar X-Fynex-Signature.
• Respondé rápido — Devolvé 200 inmediatamente y procesá en background.
• Sé idempotente — Usá X-Fynex-Delivery para detectar entregas duplicadas. Puede ocurrir que Fynex reintente una entrega que ya habías procesado.
• Usá HTTPS — En producción, tu endpoint debe usar HTTPS para proteger los datos en tránsito.
• Monitoreá las fallas — Si tu webhook se desactiva por reintentos fallidos, vas a ver el estado "disabled" en la lista.