Guía Técnica de Webhooks - UnoPago
Los webhooks son el mecanismo principal para recibir notificaciones automáticas sobre eventos ocurridos en su cuenta de UnoPago. En lugar de realizar peticiones constantes a nuestra API (polling), nuestro sistema enviará peticiones HTTP POST en tiempo real a su servidor cada vez que ocurra una acción relevante.
1. Configuración del Webhook
Siga estos pasos para integrar el flujo de eventos en su aplicación:
Paso 1: Registro del Endpoint
- Acceda al panel de control y diríjase a la sección Webhooks.
- Haga clic en el botón Crear Webhook.
- Complete los siguientes parámetros técnicos:
- URL: El endpoint de su servidor que recibirá las peticiones (debe ser una dirección HTTPS válida).
- Descripción: Un identificador interno para gestionar múltiples integraciones.
- Eventos: Selección de los disparadores (triggers) que activarán la notificación.
Paso 2: Catálogo de Eventos Disponibles
A continuación, se detallan los eventos que puede suscribir:
| Categoría | Evento | Descripción |
|---|---|---|
| Pagos | payment_received | Se activa tras la confirmación exitosa de una transacción. |
| Facturas | invoice_created | Se dispara al generar un nuevo documento fiscal o proforma. |
| Clientes | customer_updated | Notifica cambios en el perfil o metadatos de un cliente. |
Paso 3: Validación y Pruebas
Una vez guardada la configuración, utilice la herramienta "Probar Webhook". El sistema enviará un payload de prueba para verificar que su servidor retorna un código de estado 200 OK.
2. Seguridad y Verificación de Firmas
Para garantizar la integridad de los datos y confirmar que la petición proviene exclusivamente de UnoPago, cada notificación incluye una firma digital.
- Cabecera: Localice el header
Webhook-Signatureen la petición entrante. - Validación: Utilice su Llave Secreta (disponible en la configuración de su panel) para verificar el hash de la firma.
- Integridad: Descarte cualquier petición que no supere la validación de firma para prevenir ataques de suplantación (spoofing).
3. Buenas Prácticas y Requisitos Técnicos
Para asegurar una integración robusta, considere los siguientes puntos:
- Tiempo de Respuesta: Su servidor debe procesar la solicitud y responder en un intervalo menor a 5 segundos.
- Procesamiento Asíncrono: Recomendamos responder inmediatamente con un código
200 OKy procesar la lógica de negocio en segundo plano (background tasks). - Idempotencia: Asegúrese de que su implementación sea idempotente. En caso de reintentos, su sistema debe ser capaz de manejar el mismo evento múltiples veces sin duplicar acciones.
- Política de Reintentos: Si su servidor no está disponible (retorna errores 5xx o 4xx), UnoPago ejecutará una política de 20 reintentos exponenciales antes de desactivar el webhook automáticamente.
Nota: Mantenga su Llave Secreta en un lugar seguro y nunca la comparta en repositorios públicos.