Webhooks - Fluz

Los webhooks permiten que tu aplicación reciba notificaciones en tiempo real cuando ocurren eventos en la plataforma de Fluz. En lugar de hacer polling para detectar cambios, registras un endpoint HTTPS y Fluz te envía los datos del evento en el momento en que sucede algo: una transacción con tarjeta virtual, una compra rechazada, un depósito completado, un usuario vinculando su cuenta mediante OAuth y más.

Esta página cubre todos los eventos de webhook, que abarcan múltiples áreas de la plataforma (actividad de transacciones, depósitos, flujos de widget y vinculación de cuentas por OAuth) en lugar de pertenecer a una sola función.

Los webhooks funcionan en todos los tipos de aplicaciones en la plataforma de Fluz: apps privadas que operan en tu propia cuenta, apps públicas OAuth que actúan en nombre de otros usuarios vía API y apps de widgets embebidos.

Cómo funciona

Registras una URL de webhook en tu aplicación dentro del Portal de Desarrolladores.
Seleccionas qué tipos de evento escuchar (o te suscribes a todos).
Cuando ocurre un evento coincidente, Fluz envía un POST HTTP a tu URL con un payload JSON firmado.
Tu servidor verifica la firma, responde con un 2xx y procesa el evento.

Si tu endpoint no está disponible o devuelve un error, Fluz reintenta hasta 5 veces con backoff exponencial antes de desistir de esa entrega.

Webhooks por tipo de app

Cómo se enrutan los eventos a tu app depende de tu modelo de aplicación.

Apps privadas — tu propia cuenta

Los webhooks se disparan por actividad en tu propia cuenta. Cualquier transacción, rechazo o depósito en cuentas que posees activa webhooks registrados en tu app. Casos de uso comunes: notificaciones cuando se autoriza o liquida una transacción de tarjeta virtual; alertas en tiempo real de rechazos; monitoreo de depósitos y cambios de balance en tus cuentas de gasto.

Apps públicas (OAuth) — actuando en nombre de usuarios

Los webhooks se disparan por actividad en cuentas que han autorizado tu app. Cuando un usuario concede acceso a tu app mediante OAuth, sus eventos se enrutan a tus webhooks registrados, siempre que la concesión OAuth del usuario incluya los scopes requeridos. Esto funciona tanto si el usuario interactúa a través de tu integración directa por API como mediante un widget embebido; el requisito clave es una relación OAuth entre el usuario y tu app. Casos de uso comunes: saber cuándo un usuario ha vinculado (o vuelto a vincular) su cuenta con tu app; monitorear el gasto con tarjeta virtual en cuentas conectadas; notificaciones de rechazos en tiempo real; seguimiento de depósitos completados; recibir actualizaciones de estado KYC y KYB. Las apps de widget son una app pública especializada. Los eventos se enrutan del mismo modo (basados en la relación OAuth) y, adicionalmente, las apps de widget soportan eventos específicos del widget como finalización de transferencias y compras de tarjetas de regalo.

Tipos de eventos

Fluz solo entrega un evento si tu aplicación — y, para apps públicas/OAuth, la concesión OAuth del usuario individual — posee los scopes requeridos. Los eventos sin scopes requeridos (como OAUTH_USER_LINKED) se entregan a cualquier app pública/OAuth suscrita.

Eventos de transacción

Cubren el ciclo de vida completo de la transacción. Aplican a todos los tipos de app.

Evento	Descripción	Scopes requeridos
`TRANSACTION_CREATE`	Se creó una nueva transacción (por ejemplo, compra con tarjeta virtual, depósito, transferencia).	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_UPDATE`	Cambió el estado o monto de una transacción (por ejemplo, liquidada, ajustada).	`LIST_PAYMENT`, `LIST_PURCHASES`
`TRANSACTION_DECLINE`	Se rechazó una transacción (por ejemplo, fondos insuficientes, controles de tarjeta).	`LIST_PAYMENT`, `LIST_PURCHASES`

Eventos de depósito

Evento	Descripción	Scopes requeridos
`DEPOSIT_COMPLETE`	Se completó un depósito desde una fuente de fondos hacia una cuenta de gasto.	`MAKE_DEPOSIT`

Eventos KYC y KYB

Aplican a apps públicas/OAuth y de widget. Al igual que OAUTH_USER_LINKED, estos eventos no tienen equivalente en apps privadas: solo se disparan para cuentas conectadas mediante una relación OAuth, y solo cuando la concesión OAuth de tu app (y la del usuario) incluye el scope requerido.

Evento	Descripción	Scopes requeridos
`KYC_STATUS_UPDATE`	Cambió el estado de verificación de identidad (KYC) de un usuario conectado.	`VERIFY_KYC`
`KYB_STATUS_UPDATE`	Cambió el estado de verificación (KYB) de un negocio conectado.	`REGISTER_BUSINESS`

Eventos de OAuth

Aplican a apps públicas/OAuth y de widget.

Evento	Descripción	Scopes requeridos
`OAUTH_USER_LINKED`	Un usuario completó la vinculación por OAuth con tu aplicación. Se dispara tanto en el enlace inicial como en actualizaciones posteriores (por ejemplo, cuando cambian los scopes concedidos).	Ninguno

OAUTH_USER_LINKED se entrega solo a tipos de app públicas/OAuth; los suscriptores de apps privadas no lo reciben. Dado que no tiene requisito de scope, lo recibes por cada usuario que vincule o vuelva a vincular su cuenta con tu app, sin importar qué scopes concedan. Úsalo para aprovisionar o actualizar tu registro local del usuario conectado, capturar el conjunto de scopes otorgados y mapear tu propio identificador de usuario mediante externalReferenceId. Aplican a integraciones de widget y OAuth donde los usuarios interactúan a través de flujos embebidos de Fluz.

Evento	Descripción	Scopes requeridos
`WIDGET_KYC_INITIATION`	Un usuario inició la verificación de identidad (KYC).	`VERIFY_KYC`
`WIDGET_DEPOSIT_COMPLETE`	Se completó una transferencia de un cliente hacia tu app.	`MAKE_PAYOUT_TRANSFER_SEND`
`WIDGET_WITHDRAW_COMPLETE`	Se completó una transferencia de tu app hacia un cliente.	`MAKE_PAYOUT_TRANSFER_RECEIVE`
`WIDGET_PURCHASE_GIFT_CARD`	Se completó una compra de tarjeta de regalo.	`PURCHASE_GIFTCARD`

📘 Nota sobre nombres: WIDGET_DEPOSIT_COMPLETE y WIDGET_WITHDRAW_COMPLETE describen transferencias cliente↔app; el lenguaje DEPOSIT/WITHDRAW es histórico. Trata “depósito” como “cliente → app” y “retiro” como “app → cliente”.

Configuración de webhooks

1. Abre el Portal de Desarrolladores

Ve al Portal de Desarrolladores y selecciona tu aplicación.

2. Abre la sección de Webhooks

Apps OAuth: pestaña OAuth → Webhook URLs.
Apps de widget: pestaña Widget → Webhook URLs.
Apps API / privadas: la sección Webhook URLs en la configuración de tu app.

3. Agrega una URL de webhook

Haz clic en Add new URL e ingresa tu endpoint HTTPS (por ejemplo, https://api.yourapp.com/webhooks/fluz).

4. Selecciona eventos

Elige los tipos de evento que quieres recibir.

5. Guarda

Haz clic en Create Webhook. Tu endpoint comienza a recibir eventos de inmediato.

Gestión de webhooks

Múltiples endpoints: puedes registrar más de una URL de webhook por aplicación.
Cambiar eventos suscritos: elimina el webhook y vuelve a crearlo con la nueva selección de eventos.
Eliminar un webhook: haz clic en Remove junto a él. El webhook se archiva de inmediato y deja de recibir eventos.

Recepción de webhooks

Formato de la solicitud

Cada webhook se entrega como un POST HTTP con estos headers:

Header	Descripción
`Content-Type`	Siempre `application/json`.
`X-HMAC-Signature`	Firma HMAC-SHA256 del cuerpo JSON en bruto, firmada con la clave API de tu app.
`X-Event-ID`	UUID único para este evento; úsalo para desduplicación.

El cuerpo es un objeto JSON, y cada payload incluye un campo eventType que identifica el evento.

Requisitos del endpoint

Solo HTTPS: endpoints HTTP simples se rechazan al momento del registro.
Públicamente accesible y capaz de aceptar solicitudes POST.
Responder con un 2xx dentro de 30 segundos. Respuestas no-2xx o timeouts activan reintentos.
Verificar la firma HMAC en cada solicitud.

Verificación de firmas

Cada entrega incluye un header X-HMAC-Signature: un hash HMAC-SHA256 del JSON en bruto, firmado con la clave API de tu aplicación. Verifícalo siempre antes de confiar en un payload.

⚠️ Verifica contra el cuerpo de la solicitud en bruto. Calcula el HMAC sobre los bytes exactos que envió Fluz; no reserialices el JSON parseado. Volver a convertir a string puede reordenar claves o cambiar espacios en blanco y provocar que firmas válidas fallen. Los ejemplos a continuación capturan el cuerpo en bruto por esta razón.

Node.js (Express)

const express = require('express');
const crypto = require('crypto');
const app = express();
 
// Capture the raw body so the HMAC is computed over the exact bytes Fluz sent.
app.use('/webhooks/fluz', express.raw({ type: 'application/json' }));
 
function verifyFluzWebhook(rawBody, signature, apiKey) {
  const expected = crypto.createHmac('sha256', apiKey).update(rawBody).digest('hex');
  const received = Buffer.from(signature || '', 'hex');
  const computed = Buffer.from(expected, 'hex');
  return received.length === computed.length &&
         crypto.timingSafeEqual(received, computed);
}
 
app.post('/webhooks/fluz', (req, res) => {
  const signature = req.headers['x-hmac-signature'];
  const eventId = req.headers['x-event-id'];
 
  // req.body is a Buffer because of express.raw above
  if (!verifyFluzWebhook(req.body, signature, process.env.FLUZ_API_KEY)) {
    return res.status(401).send('Invalid signature');
  }
 
  // Acknowledge immediately, then process asynchronously
  res.status(200).send('OK');
 
  const event = JSON.parse(req.body.toString('utf8'));
  handleEvent(eventId, event).catch(err =>
    console.error('Webhook processing error:', err)
  );
});

Python (Flask)

import hmac, hashlib
from flask import Flask, request
 
app = Flask(__name__)
 
def verify_fluz_webhook(raw_body: bytes, signature: str, api_key: str) -> bool:
    expected = hmac.new(api_key.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")
 
@app.post("/webhooks/fluz")
def fluz_webhook():
    signature = request.headers.get("X-HMAC-Signature")
    event_id = request.headers.get("X-Event-ID")
 
    # request.get_data() returns the raw bytes — do NOT use request.json for verification
    if not verify_fluz_webhook(request.get_data(), signature, FLUZ_API_KEY):
        return "Invalid signature", 401
 
    enqueue(event_id, request.get_json())  # process asynchronously
    return "OK", 200

Responder a los webhooks

Tu endpoint debe:

Responder con un estado 2xx dentro de 30 segundos.
Responder rápido: confirma primero y luego procesa de forma asíncrona.
Ser accesible por HTTPS. Tu endpoint no debe:
Responder con redirecciones (3xx).
Responder con 4xx/5xx para webhooks válidos (esto activa reintentos).

Política de reintentos

Comportamiento	Detalle
Intentos máximos	5
Programación	Backoff exponencial
Disparador	Cualquier respuesta no-`2xx` o timeout
Timeout	30 segundos por intento
Después de que fallen todos los reintentos	La entrega se abandona; no hay más intentos.

Los nuevos eventos reanudan la entrega automáticamente una vez que tu endpoint se recupere. Para reenviar eventos cuyos reintentos ya se agotaron, contacta soporte con el X-Event-ID correspondiente.

Idempotencia y orden

Los webhooks pueden entregarse más de una vez, y no se garantiza el orden de entrega.

Desduplica usando el header X-Event-ID. Conserva los IDs procesados (Redis o una base de datos en producción) y omite eventos que ya manejaste.
Ordena por los datos, no por la llegada. Si el orden importa, ordénalo por timestamps del payload (createdAt, updatedAt, transactionDateTime) y por IDs de evento.

const seen = new Set(); // use Redis or a database in production
 
async function handleEvent(eventId, event) {
  if (seen.has(eventId)) return;  // already processed — skip
  seen.add(eventId);
 
  switch (event.eventType) {
    case 'TRANSACTION_CREATE':    await onTransactionCreated(event); break;
    case 'TRANSACTION_UPDATE':    await onTransactionUpdated(event); break;
    case 'TRANSACTION_DECLINE':   await onTransactionDeclined(event); break;
    case 'DEPOSIT_COMPLETE':      await onDepositComplete(event); break;
    case 'OAUTH_USER_LINKED':     await onUserLinked(event); break;
    case 'KYC_STATUS_UPDATE':     await onKycStatusUpdate(event); break;
    case 'KYB_STATUS_UPDATE':     await onKybStatusUpdate(event); break;
    case 'WIDGET_KYC_INITIATION': await onKycInitiated(event); break;
    // ...handle remaining widget events
  }
}

Identificación de la app y el usuario

Usuario: userId es el ID de usuario de Fluz. Para eventos de OAuth/widget, externalReferenceId se asigna a tu identificador de usuario desde el flujo OAuth.
App: los payloads de transacción incluyen connectedAppId y connectedAppName. Si enrutas múltiples apps a un solo endpoint, ramifica según connectedAppId. Para OAUTH_USER_LINKED, la app se identifica por appId.

Referencia de payloads

Cada payload incluye un eventType. La disponibilidad de campos puede variar según el evento; los handlers deben ignorar campos no reconocidos para mantener compatibilidad futura.

📘 Una nota sobre los valores de status. Para transacciones creadas/actualizadas, el campo status toma uno de PENDING, SETTLED o FAILED. Las transacciones rechazadas llevan un status de DECLINED (o FAILED). Versiones anteriores de esta página mostraban COMPLETED como estado; ese valor no se emite; usa SETTLED para detectar una transacción finalizada.

Transacción creada (`TRANSACTION_CREATE`)

Se dispara para cualquier transacción nueva: compras con tarjeta virtual, depósitos, transferencias y más.

{
  "eventType": "TRANSACTION_CREATE",
  "recordId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "transactionType": "PURCHASE",
  "amount": 42.99,
  "destination": "Coffee Shop",
  "source": "Virtual Card",
  "status": "PENDING",
  "channel": "VIRTUAL_CARD",
  "connectedAppId": "your-app-id",
  "connectedAppName": "Your App",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "merchantName": "Coffee Shop",
  "merchantCity": "New York",
  "merchantState": "NY",
  "merchantCountry": "US",
  "cardLastFour": "1234",
  "virtualCardId": "vc-uuid-here",
  "digitalWalletProvider": "APPLE_PAY",
  "digitalWalletToken": "dw_2204zdpwi8352fa1jvhs2nl0ikgvdgnism",
  "isReversal": false,
  "cashbackRate": 0.05
}

Campo	Tipo	Descripción
`eventType`	String	Siempre `TRANSACTION_CREATE`.
`recordId`	String (UUID)	ID único del registro del evento de webhook.
`transactionId`	String (UUID)	El ID de la transacción.
`accountId`	String (UUID)	El ID de la cuenta de Fluz.
`userId`	String (UUID)	El ID de usuario de Fluz. Puede estar ausente en algunas transacciones generadas por el sistema.
`transactionType`	String	Tipo de transacción, p. ej., `PURCHASE`, `GIFT_CARD_PURCHASE`, `DEPOSIT`, `WITHDRAWAL`, `TRANSFER`. Trátalo como una cadena abierta.
`amount`	Number	Monto de la transacción en USD.
`destination`	String	A dónde fueron los fondos (por ejemplo, nombre del comercio).
`source`	String	Fuente de fondos (por ejemplo, `Virtual Card`).
`status`	String (enum)	Uno de `PENDING`, `SETTLED`, `FAILED`.
`channel`	String	Origen/canal de la transacción (por ejemplo, `VIRTUAL_CARD`). Trátalo como una cadena abierta.
`connectedAppId`	String	La app a la que se enruta el evento. Puede estar ausente para actividad de apps privadas.
`connectedAppName`	String	Nombre visible de la app conectada.
`createdAt`	String (ISO 8601)	Cuándo se creó la transacción.
`merchantName` / `merchantCity` / `merchantState` / `merchantCountry`	String	Detalles de ubicación del comercio.
`cardLastFour`	String	Últimos cuatro dígitos de la tarjeta usada.
`virtualCardId`	String (UUID)	El ID de la tarjeta virtual, si aplica.
`digitalWalletProvider`	String (enum)	Presente cuando una transacción con tarjeta se realizó a través de una billetera móvil. Uno de `APPLE_PAY`, `GOOGLE_PAY` (se pueden agregar más con el tiempo). Ausente o `null` para transacciones sin billetera. Este es el campo a usar para determinar que una transacción fue un pago con billetera móvil.
`digitalWalletToken`	String	Identificador de token de red para la tarjeta tokenizada (por ejemplo, `dw_...`). No es un indicador de billetera por sí solo: también se establece para tokens de red sin billetera (como una tarjeta almacenada por un comercio) y puede estar ausente en algunas transacciones de billetera. Usa `digitalWalletProvider`, no la presencia de este token, para decidir si un pago provino de una billetera móvil.
`isReversal`	Boolean	`true` cuando la transacción es una reversión de autorización. Ver Reversiones vs reembolsos abajo.
`cashbackRate`	Number	Tasa de cashback decimal (por ejemplo, `0.05` = 5%).

Transacción actualizada (`TRANSACTION_UPDATE`)

Se dispara cuando cambian el estado o los detalles de una transacción; por ejemplo, cuando una autorización pendiente se liquida.

{
  "eventType": "TRANSACTION_UPDATE",
  "recordId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "transactionType": "PURCHASE",
  "amount": 42.99,
  "status": "SETTLED",
  "connectedAppId": "your-app-id",
  "connectedAppName": "Your App",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-16T08:00:00.000Z",
  "isReversal": false
}

Los campos coinciden con TRANSACTION_CREATE donde aparecen, más updatedAt (ISO 8601) que marca cuándo ocurrió el cambio. userId, connectedAppId y connectedAppName se mantienen de la misma forma que en TRANSACTION_CREATE, por lo que puedes identificar al usuario y la app de manera consistente a lo largo del ciclo de vida. Una transición de status a SETTLED es la señal de que una transacción previamente pendiente se ha finalizado. isReversal conserva el mismo significado aquí que en TRANSACTION_CREATE. Ver Reversiones vs reembolsos.

Transacción rechazada (`TRANSACTION_DECLINE`)

Se dispara cuando se rechaza una transacción. Incluye motivos de rechazo estructurados sobre los que tu app puede actuar.

{
  "eventType": "TRANSACTION_DECLINE",
  "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "transactionType": "PURCHASE",
  "amount": 500.00,
  "fluzAmount": 500.00,
  "externalFundingAmount": 0,
  "currency": "USD",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DECLINED",
  "merchantName": "Electronics Store",
  "cardLastFour": "1234",
  "virtualCardId": "vc-uuid-here",
  "isCashBalanceUsed": true,
  "isPrepaymentBalanceUsed": false,
  "isRewardsBalanceUsed": false,
  "isReserveBalanceUsed": false,
  "isReversal": false,
  "transactionDateTime": "2025-01-15T10:30:00.000Z",
  "declineTitle": "Transaction Declined",
  "declineReason": "Insufficient funds",
  "declineDescription": "Your account balance was not sufficient for this transaction.",
  "declineCategory": "Balance"
}

Campo	Tipo	Descripción
`amount`	Number	Monto total intentado.
`fluzAmount`	Number	Porción tomada del balance de Fluz.
`externalFundingAmount`	Number	Porción tomada de fondos externos.
`currency`	String	Código de moneda ISO (por ejemplo, `USD`).
`status`	String (enum)	Uno de `DECLINED`, `FAILED`.
`userId`	String (UUID)	El ID de usuario de Fluz. Puede estar ausente en algunas transacciones generadas por el sistema.
`isCashBalanceUsed` / `isPrepaymentBalanceUsed` / `isRewardsBalanceUsed` / `isReserveBalanceUsed`	Boolean	Desde qué tipo(s) de balance se intentó tomar.
`isReversal`	Boolean	`true` para una reversión de autorización. Ver Reversiones vs reembolsos.
`transactionDateTime`	String (ISO 8601)	Cuándo ocurrió el rechazo.
`declineTitle`	String	Título corto orientado al usuario.
`declineReason`	String	Motivo breve (por ejemplo, `Insufficient funds`).
`declineDescription`	String	Explicación más larga orientada al usuario.
`declineCtaText`	String	Acción sugerida de resolución, cuando esté disponible (por ejemplo, `Add money`).
`declineCategory`	String	Agrupación de rechazo de alto nivel. Valores comunes incluyen `Balance`, `Limit`, `Validation`, `Virtual Card` y `Acquiring`. Trátalo como una cadena abierta y consulta Códigos de Rechazo para el conjunto completo y el detalle por código.

Campos opcionales adicionales pueden estar presentes según la transacción (p. ej., merchantId, merchantCity, merchantState, merchantCountry, cardDisplayName, virtualCardProgram, channel, bankAccountNickname, bankAccountLastFour). Ignora los que no uses.

Reversiones vs reembolsos

Una reversión libera una retención de autorización antes de que se capture dinero. El saldo disponible del tarjetahabiente vuelve a subir, pero nunca salieron fondos y no regresa ningún dinero. Un reembolso ocurre después de una captura: el dinero se movió y el comercio lo devolvió. isReversal diferencia ambos:

Valor	Significado
`true`	Una reversión de autorización. Se liberó la retención y no se capturó nada.
`false`	Cualquier cosa que clasificamos que no sea una reversión, como una autorización, una captura, un reembolso genuino o un rechazo.
ausente	No pudimos clasificar la transacción, generalmente porque la actividad subyacente de la tarjeta aún no nos ha llegado. Trátalo como desconocido en lugar de `false`.

Usa este campo en lugar de transactionType. Los emisores de tarjetas etiquetan estos eventos de forma inconsistente, por lo que el valor de tipo de un emisor para un reembolso de comercio es el de otro para una reversión previa a la captura, y el tipo por sí solo no puede decirte si realmente se movió dinero. Qué evento lleva una reversión depende de lo que se revirtió:

Una retención liberada sobre una compra que ya conoces llega como TRANSACTION_UPDATE en esa transacción.
Una anulación de verificación de tarjeta se registra como su propia transacción, por lo que llega como TRANSACTION_CREATE con un amount negativo y luego se actualiza. Estas son las pequeñas verificaciones que hace un comercio para confirmar que una tarjeta es válida y que anulamos de inmediato.

Una reversión no es una falla, pero requiere manejo: libera la retención que registraste para la autorización correspondiente, o permanecerá abierta de tu lado para siempre. No la registres como una nueva salida, ya que no se movió dinero.

Depósito completado (`DEPOSIT_COMPLETE`)

Se dispara cuando se completa un depósito desde una fuente de fondos hacia una cuenta de gasto.

{
  "eventType": "DEPOSIT_COMPLETE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 50.00
}

Usuario de OAuth vinculado (`OAUTH_USER_LINKED`)

Se dispara cuando un usuario completa la vinculación por OAuth con tu aplicación, tanto en el enlace inicial como en actualizaciones posteriores (por ejemplo, cuando el usuario vuelve a autorizar con un conjunto distinto de scopes). Solo apps públicas/OAuth y de widget. No se requiere ningún scope para recibir este evento.

{
  "eventType": "OAUTH_USER_LINKED",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "appId": "55555555-5555-4555-8555-555555555555",
  "externalReferenceId": "your-reference-123",
  "scopes": [
    "LIST_PAYMENT",
    "MAKE_DEPOSIT"
  ],
  "spendAccountAccess": {
    "restricted": true,
    "userCashBalanceIds": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ],
    "includesFutureSpendAccounts": false
  }
}

Campo	Tipo	Descripción
`eventType`	String	Siempre `OAUTH_USER_LINKED`.
`accountId`	String (UUID)	El ID de la cuenta de Fluz que vinculó con tu app.
`userId`	String (UUID)	El ID de usuario de Fluz que vinculó con tu app.
`appId`	String (UUID)	El ID de tu aplicación.
`externalReferenceId`	String	Opcional. Tu identificador de usuario pasado a través del flujo OAuth. Presente para tipos de app de widget y cualquier flujo que lo haya suministrado; puede estar ausente en otros casos.
`scopes`	String[]	Las claves de scope distintas concedidas por este usuario (por ejemplo, `LIST_PAYMENT`, `MAKE_DEPOSIT`).
`spendAccountAccess`	Object	Solo en staging por ahora; aún no se entrega en producción. Indica sobre cuáles cuentas de gasto del usuario puede actuar esta vinculación. Ver Acceso a cuentas de gasto más abajo.
`spendAccountAccess.restricted`	Boolean	`true` cuando el usuario concedió a tu app acceso solo a cuentas de gasto específicas; `false` cuando la concesión cubre todas las cuentas de gasto del usuario.
`spendAccountAccess.userCashBalanceIds`	String (UUID)[] \| null	Solo en staging por ahora; aún no se entrega en producción. El `userCashBalanceId` de cada cuenta de gasto concedida cuando `restricted` es `true`. Siempre `null` cuando `restricted` es `false`.
`spendAccountAccess.includesFutureSpendAccounts`	Boolean	Indica si las cuentas de gasto que el usuario abra después de vincular se agregan automáticamente a una concesión restringida. Solo tiene sentido cuando `restricted` es `true`; ver Acceso a cuentas de gasto.

Debido a que OAUTH_USER_LINKED se dispara nuevamente en re-vinculaciones/actualizaciones, trátalo como un upsert: crea al usuario conectado al recibirlo por primera vez y actualiza el conjunto de scopes almacenado en entregas posteriores.

Acceso a cuentas de gasto

Cuando un usuario vincula su cuenta con tu app, el paso de permisos le permite conceder acceso a todas sus cuentas de gasto o solo a las que elija. spendAccountAccess te indica con cuál de las dos opciones quedó la vinculación, para que puedas empezar a operar sobre una cuenta de gasto — por ejemplo, llamar a getSpendAccountPaymentInstructions para generar instrucciones de depósito — sin una consulta adicional justo después de la vinculación.

Concesión restringida. restricted es true y userCashBalanceIds lista las cuentas de gasto que el usuario seleccionó al vincular. Por ahora los IDs se entregan solo en staging; las entregas en producción aún no los incluyen. includesFutureSpendAccounts te indica si esa lista es fija:
- false — la concesión cubre exactamente estas cuentas de gasto. La lista solo cambia si el usuario vuelve a vincular, lo que envía un nuevo evento OAUTH_USER_LINKED.
- true — el operador permitió que el usuario incluya las cuentas de gasto que abra después. Cada cuenta de gasto nueva se agrega a la concesión automáticamente, pero abrirla no dispara este evento, así que userCashBalanceIds solo es exacto al momento de la vinculación. Llama a getWallet con el token de acceso del usuario para obtener la lista actual.
Concesión sin restricción. restricted es false y userCashBalanceIds es null. La concesión cubre todas las cuentas de gasto que el usuario tiene ahora y cualquiera que abra después. Fluz no enumera las cuentas de gasto actuales en el payload, porque abrir una nueva cuenta de gasto no dispara este evento y la instantánea quedaría desactualizada. Llama a getWallet con el token de acceso del usuario para obtener la lista actual.

{
  "spendAccountAccess": {
    "restricted": false,
    "userCashBalanceIds": null
  }
}

Solo se incluyen IDs. No se incluyen apodos ni saldos, porque pueden cambiar sin disparar este evento; léelos desde getWallet, cuyo balances.userCashBalances ya viene filtrado a las cuentas de gasto que la vinculación permite. El evento se dispara de nuevo con el valor actualizado cada vez que cambia la concesión: el usuario vuelve a dar su consentimiento, cambian los scopes concedidos o cambian las cuentas de gasto concedidas aunque los scopes sigan iguales (por ejemplo, el usuario reemplaza una cuenta de gasto por otra). Trata la última entrega como la autoritativa y reemplaza, en lugar de fusionar, la lista de IDs almacenada. Trata este campo como una conveniencia. Las entregas de webhooks pueden llegar tarde o fuera de orden, así que si necesitas tener certeza de qué cuentas de gasto permite una vinculación, llama a getWallet: es la fuente de verdad.

Solo en stagingspendAccountAccess en OAUTH_USER_LINKED actualmente se entrega solo en el entorno de staging. Las entregas en producción aún no lo incluyen; esta página se actualizará cuando se despliegue.

Inicio de KYC (`WIDGET_KYC_INITIATION`)

Se dispara cuando un usuario inicia la verificación de identidad. Solo apps públicas/de widget.

{
  "eventType": "WIDGET_KYC_INITIATION",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123"
}

Transferencia completada — cliente a app (`WIDGET_DEPOSIT_COMPLETE`)

Se dispara cuando un usuario transfiere fondos a tu aplicación.

{
  "eventType": "WIDGET_DEPOSIT_COMPLETE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 25.50
}

Transferencia completada — app a cliente (`WIDGET_WITHDRAW_COMPLETE`)

Se dispara cuando tu aplicación transfiere fondos a un usuario.

{
  "eventType": "WIDGET_WITHDRAW_COMPLETE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 15.00
}

Compra de tarjeta de regalo (`WIDGET_PURCHASE_GIFT_CARD`)

Se dispara cuando se completa una compra de tarjeta de regalo a través del widget.

{
  "eventType": "WIDGET_PURCHASE_GIFT_CARD",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123",
  "amount": 25.00
}

Campos comunes de payload del widget: userId (ID de usuario de Fluz), accountId (ID de cuenta de Fluz), externalReferenceId (tu identificador de usuario desde el flujo OAuth) y amount cuando corresponda.

Actualización de estado KYC (`KYC_STATUS_UPDATE`)

Se dispara cuando cambia el estado KYC de un usuario conectado. Solo apps públicas/OAuth y de widget; requiere el scope VERIFY_KYC. Cada payload comparte un sobre común; la forma del objeto verificationData se discrimina por verificationType, mostrado por tipo a continuación.

Campo	Tipo	Descripción
`eventType`	String	Siempre `KYC_STATUS_UPDATE`.
`userId`	String (UUID)	El ID de usuario de Fluz cuyo estado KYC cambió.
`accountId`	String (UUID)	El ID de la cuenta de Fluz.
`previousStatus` / `newStatus`	String (enum)	Uno de `NOT_REQUIRED`, `PENDING_DOCUMENTS`, `MISSING_1099_INFO`, `PASS`, `PASS_INTERNATIONAL`, `SOFT_DECLINE`, `HARD_DECLINE`, `FAIL`.
`externalReferenceId`	String	Opcional. Tu identificador de usuario desde el flujo OAuth.
`verificationType`	String (enum)	Uno de `SSN`, `DOCUMENTS`, `SYSTEM`. Discrimina la forma de `verificationData`, mostrada por tipo en las pestañas abajo.

SSN
Documents
System

Emitido cuando el cambio de estado resultó de una verificación basada en SSN.

{
  "eventType": "KYC_STATUS_UPDATE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "previousStatus": "PENDING_DOCUMENTS",
  "newStatus": "PASS",
  "externalReferenceId": "your-reference-123",
  "verificationType": "SSN",
  "verificationData": {
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "userDateOfBirth": "1990-01-15T00:00:00.000Z",
    "lastFourSSNDigits": "6789",
    "legalAddress": {
      "streetAddressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }
}

Campo	Tipo	Descripción
`verificationData.userFirstName`	String	Nombre legal del usuario.
`verificationData.userLastName`	String	Apellido legal del usuario.
`verificationData.userDateOfBirth`	String (ISO 8601)	Opcional. Fecha de nacimiento del usuario.
`verificationData.lastFourSSNDigits`	String	Opcional. Últimos cuatro dígitos del SSN usado para la verificación.
`verificationData.legalAddress`	Object	Opcional. Ver forma abajo.

Emitido cuando el cambio de estado resultó de una verificación de identidad basada en documentos.

{
  "eventType": "KYC_STATUS_UPDATE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "previousStatus": "PENDING_DOCUMENTS",
  "newStatus": "PASS",
  "externalReferenceId": "your-reference-123",
  "verificationType": "DOCUMENTS",
  "verificationData": {
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "userDateOfBirth": "1990-01-15T00:00:00.000Z",
    "documentType": "PASSPORT",
    "documentId": "b3f8b6d0-1234-4a5b-9c3d-abcdefabcdef",
    "documentIssuer": "US",
    "documentIssueDate": "2020-05-01T00:00:00.000Z",
    "documentExpireDate": "2030-05-01T00:00:00.000Z",
    "legalAddress": {
      "streetAddressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }
}

Campo	Tipo	Descripción
`verificationData.userFirstName`	String	Nombre legal del usuario.
`verificationData.userLastName`	String	Apellido legal del usuario.
`verificationData.userDateOfBirth`	String (ISO 8601)	Opcional. Fecha de nacimiento del usuario.
`verificationData.documentType`	String	Opcional. Tipo de documento presentado (por ejemplo, `PASSPORT`).
`verificationData.documentId`	String (UUID)	Opcional. ID de Fluz para el documento presentado.
`verificationData.documentIssuer`	String	Opcional. País/autoridad emisora.
`verificationData.documentIssueDate`	String (ISO 8601)	Opcional. Cuándo se emitió el documento.
`verificationData.documentExpireDate`	String (ISO 8601)	Opcional. Cuándo vence el documento.
`verificationData.legalAddress`	Object	Opcional. Ver forma abajo.

Emitido para cambios de estado impulsados por el sistema que no están vinculados a un SSN o una presentación de documento específica (por ejemplo, una reevaluación automática). verificationData en sí es opcional aquí: puede estar completamente ausente.

{
  "eventType": "KYC_STATUS_UPDATE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "previousStatus": "SOFT_DECLINE",
  "newStatus": "HARD_DECLINE",
  "externalReferenceId": "your-reference-123",
  "verificationType": "SYSTEM",
  "verificationData": {
    "reason": "Failed secondary AML screening"
  }
}

Campo	Tipo	Descripción
`verificationData`	Object	Opcional. Puede estar completamente ausente.
`verificationData.reason`	String	Opcional. Motivo en texto libre para el cambio impulsado por el sistema.

legalAddress, cuando está presente (solo tipos SSN y DOCUMENTS), tiene la forma { streetAddressLine1, streetAddressLine2 (optional), city, state, postalCode, country }.

Actualización de estado KYB (`KYB_STATUS_UPDATE`)

Se dispara cuando cambia el estado KYB de un negocio conectado. Solo apps públicas/OAuth; requiere el scope REGISTER_BUSINESS.

{
  "eventType": "KYB_STATUS_UPDATE",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "previousStatus": "IN_PROGRESS",
  "newStatus": "PASS",
  "externalReferenceId": "your-reference-123"
}

Campo	Tipo	Descripción
`eventType`	String	Siempre `KYB_STATUS_UPDATE`.
`accountId`	String (UUID)	El ID de la cuenta de Fluz del negocio.
`userId`	String (UUID)	Opcional. El ID de usuario de Fluz asociado con el negocio, cuando esté disponible.
`previousStatus` / `newStatus`	String (enum)	Uno de `IN_PROGRESS`, `SUBMITTED_FOR_APPROVAL`, `PASS`, `REVIEW`, `FAILED`, `SOFT_DECLINE`, `HARD_DECLINE`, `PENDING_FORMATION`, `PENDING_DOCUMENTS`, `PASS_INTERNATIONAL`, `WAITING_FOR_SCREENING_RESULT`.
`externalReferenceId`	String	Opcional. Tu identificador de usuario desde el flujo OAuth.

Mejores prácticas

Responde rápido, procesa después. Devuelve 200 de inmediato y maneja el evento de forma asíncrona para evitar timeouts y reintentos innecesarios.
Verifica cada solicitud. Valida X-HMAC-Signature contra el cuerpo en bruto usando tu clave API antes de procesar.
Desduplica con IDs de evento. Rastrea X-Event-ID para manejar entregas reintentadas/duplicadas.
Trata los campos tipo enum como cadenas abiertas. Con el tiempo pueden aparecer nuevos valores de transactionType, channel y declineCategory; ramifica según los valores que te interesen y tolera los desconocidos.
Upsert en OAUTH_USER_LINKED. Puede dispararse más de una vez por usuario; actualiza el conjunto de scopes almacenado y spendAccountAccess cada vez en lugar de asumir semántica de solo primer enlace.
Acepta campos desconocidos. Los payloads pueden agregar campos con el tiempo; ignora los no reconocidos en lugar de fallar.
Monitorea tu endpoint. Alerta sobre respuestas repetidas no-2xx: después de 5 intentos fallidos seguidos se abandona la entrega de un evento.

Solución de problemas

Síntoma	Causa probable	Solución
No recibes ningún webhook	Endpoint inalcanzable o devolviendo errores	Confirma que la URL es correcta, accesible públicamente por HTTPS y que devuelve `2xx`.
Faltan ciertos tipos de evento	La app no tiene los scopes requeridos	Asegúrate de que tu app tenga los scopes listados para ese evento.
App pública no recibe eventos para un usuario	El usuario no ha autorizado los scopes requeridos	Confirma que la concesión OAuth del usuario incluye los scopes necesarios.
`spendAccountAccess.userCashBalanceIds` es `null`	La concesión no tiene restricción (`restricted: false`)	La vinculación cubre todas las cuentas de gasto del usuario, actuales y futuras. Llama a `getWallet` con el token de acceso del usuario para listarlas.
A los `userCashBalanceIds` de una concesión restringida les falta una cuenta de gasto que el usuario abrió después de vincular	`includesFutureSpendAccounts` es `true` y abrir una cuenta de gasto no dispara el evento	La cuenta de gasto nueva ya forma parte de la concesión. Llama a `getWallet` con el token de acceso del usuario para obtener la lista actual.
No recibes `OAUTH_USER_LINKED`	Suscrito en una app privada o no suscrito	Este evento es solo para apps públicas/OAuth. Suscríbete (o usa captura global) en una app OAuth o de widget.
Falla la verificación de firma	Clave API incorrecta o verificación sobre un cuerpo reserializado	Usa la clave API de tu app y verifica contra el cuerpo en bruto de la solicitud.
Entregas duplicadas	Reintento tras un timeout	Implementa idempotencia usando `X-Event-ID`.
Dejaron de llegar eventos	5 fallos consecutivos agotaron los reintentos	Arregla tu endpoint; los eventos nuevos se reanudan automáticamente. Contacta soporte para reprocesar eventos cuyos reintentos se agotaron.

¿Necesitas ayuda?

Problemas técnicos: revisa los logs de tu endpoint y contacta soporte con el X-Event-ID.
Preguntas sobre scopes: consulta Scopes de Aplicación y Códigos de Rechazo.

​Cómo funciona

​Webhooks por tipo de app

​Apps privadas — tu propia cuenta

​Apps públicas (OAuth) — actuando en nombre de usuarios

​Apps de widget

​Tipos de eventos

​Eventos de transacción

​Eventos de depósito

​Eventos KYC y KYB

​Eventos de OAuth

​Eventos específicos del widget

​Configuración de webhooks

​1. Abre el Portal de Desarrolladores

​2. Abre la sección de Webhooks

​3. Agrega una URL de webhook

​4. Selecciona eventos

​5. Guarda

​Gestión de webhooks

​Recepción de webhooks

​Formato de la solicitud

​Requisitos del endpoint

​Verificación de firmas

​Node.js (Express)

​Python (Flask)

​Responder a los webhooks

​Política de reintentos

​Idempotencia y orden

​Identificación de la app y el usuario

​Referencia de payloads

​Transacción creada (TRANSACTION_CREATE)

​Transacción actualizada (TRANSACTION_UPDATE)

​Transacción rechazada (TRANSACTION_DECLINE)

​Reversiones vs reembolsos

​Depósito completado (DEPOSIT_COMPLETE)

​Usuario de OAuth vinculado (OAUTH_USER_LINKED)

​Acceso a cuentas de gasto

​Inicio de KYC (WIDGET_KYC_INITIATION)

​Transferencia completada — cliente a app (WIDGET_DEPOSIT_COMPLETE)

​Transferencia completada — app a cliente (WIDGET_WITHDRAW_COMPLETE)

​Compra de tarjeta de regalo (WIDGET_PURCHASE_GIFT_CARD)

​Actualización de estado KYC (KYC_STATUS_UPDATE)

​Actualización de estado KYB (KYB_STATUS_UPDATE)

​Mejores prácticas

​Solución de problemas

​¿Necesitas ayuda?

Cómo funciona

Webhooks por tipo de app

Apps privadas — tu propia cuenta

Apps públicas (OAuth) — actuando en nombre de usuarios

Apps de widget

Tipos de eventos

Eventos de transacción

Eventos de depósito

Eventos KYC y KYB

Eventos de OAuth

Eventos específicos del widget

Configuración de webhooks

1. Abre el Portal de Desarrolladores

2. Abre la sección de Webhooks

3. Agrega una URL de webhook

4. Selecciona eventos

5. Guarda

Gestión de webhooks

Recepción de webhooks

Formato de la solicitud

Requisitos del endpoint

Verificación de firmas

Node.js (Express)

Python (Flask)

Responder a los webhooks

Política de reintentos

Idempotencia y orden

Identificación de la app y el usuario

Referencia de payloads

Transacción creada (`TRANSACTION_CREATE`)

Transacción actualizada (`TRANSACTION_UPDATE`)

Transacción rechazada (`TRANSACTION_DECLINE`)

Reversiones vs reembolsos

Depósito completado (`DEPOSIT_COMPLETE`)

Usuario de OAuth vinculado (`OAUTH_USER_LINKED`)

Acceso a cuentas de gasto

Inicio de KYC (`WIDGET_KYC_INITIATION`)

Transferencia completada — cliente a app (`WIDGET_DEPOSIT_COMPLETE`)

Transferencia completada — app a cliente (`WIDGET_WITHDRAW_COMPLETE`)

Compra de tarjeta de regalo (`WIDGET_PURCHASE_GIFT_CARD`)

Actualización de estado KYC (`KYC_STATUS_UPDATE`)

Actualización de estado KYB (`KYB_STATUS_UPDATE`)

Mejores prácticas

Solución de problemas

¿Necesitas ayuda?