Copy page

Desarrolladores

Webhooks

Fluxis usa webhooks a nivel de cuenta para notificar a tu aplicación en tiempo real cuando ocurren eventos, como cambios de estado de pagos. Esta guía cubre registro, comportamiento de entrega y un resumen de verificación de firmas.

Para el recorrido completo de verificación HMAC (JSON canónico, ejemplo trabajado, endpoint de prueba), consulta Verificación de firma de webhook.

Resumen

Cuando registras un webhook para una cuenta, Fluxis envía solicitudes HTTP POST a tu URL cuando ocurren eventos coincidentes. Cada solicitud incluye:

• Un payload JSON con datos del evento
• Encabezados de seguridad para verificación de firma

Encabezados de webhook

Cada solicitud de webhook incluye los siguientes encabezados:

Encabezado	Descripción
X-Request-Signature	Firma HMAC-SHA256 del payload
X-Request-Timestamp	Marca de tiempo Unix (segundos) cuando se generó la solicitud
Content-Type	Siempre application/json

Registrar webhooks

Los webhooks se gestionan a nivel de cuenta (no por Punto de Venta). Usa las credenciales de tu organización para registrar un endpoint HTTPS para la cuenta vinculada a tu POS.

Crear webhook: POST /v1/account/{accountID}/webhook

Code
{
  "url": "https://your-server.com/webhooks/fluxis",
  "event_type": "payment_request",
  "description": "Order status updates"
}

La respuesta incluye un secret — guárdalo de inmediato; solo se devuelve al crear.

event_type	Cuándo se dispara
payment_request	Cambios de estado de solicitud de pago (ver abajo)
incoming_transfer	Eventos de transferencia entrante (reservado / uso futuro)
refund	Eventos de reembolso

Otros endpoints de gestión:

Acción	Endpoint
List	GET /v1/account/{accountID}/webhook/list
Update URL	PUT /v1/account/{accountID}/webhook/{webhookID}/url
Activate	PATCH /v1/account/{accountID}/webhook/{webhookID}/activate
Deactivate	PATCH /v1/account/{accountID}/webhook/{webhookID}/deactivate
Delete	DELETE /v1/account/{accountID}/webhook/{webhookID}/delete
Test delivery	POST /v1/account/{accountID}/webhook/{webhookID}/test
Delivery logs	GET /v1/account/{accountID}/webhook/logs?page=1&page_size=20

Consulta la Referencia API — Webhooks.

---

Verificar firmas de webhook (resumen)

Fluxis firma el cuerpo JSON parseado completo — por ejemplo { "data": { … } } — no los bytes crudos de la solicitud ni solo el objeto interno data.

Algoritmo:

1. Serializa el cuerpo parseado a JSON canónico (compacto, claves ordenadas alfabéticamente en cada nivel de objeto)
2. Construye la cadena firmada: <unix_timestamp>.<canonical_json>
3. Calcula HMAC-SHA256(webhook_secret, signed_string) y codifica el resultado en hexadecimal
4. Compara con X-Request-Signature usando una función de tiempo constante
5. Rechaza si la marca de tiempo tiene más de 300 segundos (5 minutos)

Ejemplo de cadena firmada (marca de tiempo 1712345678, payload de muestra payment_request):

Code
1712345678.{"data":{"account_id":"c87464d1-c54a-48c3-80c9-bee4fddf593d","external_reference_id":"order-123","notification_type":"payment_request_status_update","payment_request_id":"aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf","payment_request_type":"fixed","point_of_sale_id":"3cc1f7ca-c017-4e7e-b00d-aca0da6e464e","status":"completed"}}

::::note Campos opcionales Campos como external_reference_id y account_id usan omitempty en la API — se omiten del JSON cuando no están definidos. Tu verificador debe canonicalizar el cuerpo parseado tal como se recibió, no una plantilla de esquema fija. ::::

Verificación rápida en Node.js (consulta la guía completa para Python, Go y un ejemplo trabajado):

Code
import crypto from "crypto";

function sortKeys(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(sortKeys);
  if (value !== null && typeof value === "object") {
    return Object.keys(value as object)
      .sort()
      .reduce((acc, key) => {
        acc[key] = sortKeys((value as Record<string, unknown>)[key]);
        return acc;
      }, {} as Record<string, unknown>);
  }
  return value;
}

function verifyWebhookSignature(
  payload: unknown,
  signature: string,
  timestamp: string,
  secret: string,
): boolean {
  const requestTimestamp = parseInt(timestamp, 10);
  if (Math.floor(Date.now() / 1000) - requestTimestamp > 300) return false;

  const canonicalJson = JSON.stringify(sortKeys(payload));
  const signedString = `${timestamp}.${canonicalJson}`;
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(signedString)
    .digest("hex");

  if (signature.length !== expectedSignature.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(signature, "utf8"),
    Buffer.from(expectedSignature, "utf8"),
  );
}

---

Qué estados disparan webhooks

Fluxis entrega webhooks payment_request cuando una solicitud de pago entra en processing (pago detectado) o un estado terminal de confirmación (completed, underpaid o overpaid).

Cambios de estado como expired o failed no se envían vía webhook — haz polling del endpoint de solicitud de pago o concilia vía transacciones.

Estructura del payload de webhook

Los webhooks de actualización de estado de solicitud de pago tienen la siguiente estructura:

Code
{
  "data": {
    "notification_type": "payment_request_status_update",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "payment_request_type": "fixed",
    "external_reference_id": "your-order-id-123",
    "status": "completed",
    "point_of_sale_id": "3cc1f7ca-c017-4e7e-b00d-aca0da6e464e",
    "account_id": "c87464d1-c54a-48c3-80c9-bee4fddf593d"
  }
}

Campo	Descripción
notification_type	Tipo de notificación (p. ej., payment_request_status_update)
payment_request_id	Identificador único de la solicitud de pago
payment_request_type	Tipo de solicitud de pago (p. ej., fixed)
external_reference_id	Tu ID de referencia interna (opcional; omitido si no está definido)
status	Nuevo estado de la solicitud de pago
point_of_sale_id	ID del Punto de Venta
account_id	ID de la cuenta asociada (opcional; omitido si no está definido)

---

Mejores prácticas

Responder rápidamente

Tu endpoint debe devolver HTTP 200 OK en 2 segundos. Si necesitas procesamiento pesado, confirma el webhook de inmediato y encola el trabajo para ejecución en segundo plano.

Code
app.post("/webhooks/fluxis", async (req, res) => {
  if (!verifyWebhookSignature(req.body, /* ... */)) {
    return res.status(401).send();
  }
  res.status(200).json({ received: true });
  processWebhookAsync(req.body).catch(console.error);
});

Manejar duplicados (idempotencia)

Puedes recibir el mismo evento de webhook varias veces. Usa payment_request_id y status para deduplicar.

Conciencia de lógica de reintentos

Si tu endpoint no responde con HTTP 200, Fluxis puede reintentar el webhook. Asegúrate de que tu manejador sea idempotente.

---

Probar webhooks

1. Expón tu servidor local con ngrok o similar durante el desarrollo.
2. Registra la URL pública vía POST /v1/account/{accountID}/webhook.
3. Dispara una entrega de prueba: POST /v1/account/{accountID}/webhook/{webhookID}/test — usa la misma ruta de firma que producción.
4. Confirma que tu manejador verifica la firma y devuelve HTTP 200.

Consulta Verificación de firma de webhook para verificación paso a paso y modos de fallo comunes.

---

Solución de problemas

Problema	Qué verificar
La firma falla	Secreto correcto de la respuesta de creación; firmar el cuerpo parseado {data:…}; reglas de JSON canónico — guía completa
No se reciben eventos	URL HTTPS pública; HTTP 200 en 2 s; webhook habilitado; event_type correcto
Faltan webhooks expired / failed	Esperado — haz polling de GET /v1/pos/{posID}/payment-request/{paymentRequestID}

---

¿Necesitas ayuda?

Contacta [email protected] con tu ID de cuenta, ID de webhook y marca de tiempo de la entrega problemática.