Configurar un webhook
Cómo registrar un endpoint de webhook en Mosce ERP: URL HTTPS, selección de eventos, secreto de firma y verificación de conectividad.
Los webhooks permiten que Mosce ERP notifique a tus sistemas externos en tiempo real cada vez que ocurre un evento relevante - una factura emitida, un pago registrado, un backup completado. Este artículo cubre el registro del primer endpoint y la verificación de que la conexión funciona.
Tiempo de lectura: ~7 min
Cuándo usar esto
- Quieres integrar Mosce ERP con un sistema externo (ERP, CRM, plataforma de automatización) que necesita recibir eventos en tiempo real.
- Vas a conectar Mosce ERP con una herramienta de automatización como n8n, Zapier o Make.
- Necesitas disparar lógica personalizada en tu servidor cada vez que ocurre un evento en Mosce ERP.
Antes de empezar
- Necesitas el permiso
tenant:webhookpara crear y administrar webhooks. - Los webhooks están disponibles a partir del plan Starter. El plan gratuito no incluye acceso a webhooks.
- Tu endpoint debe ser una URL HTTPS accesible públicamente. URLs con
http://o que resuelven a direcciones IP privadas no son aceptadas. - Prepara tu servidor receptor antes de registrar el endpoint - así puedes verificar la conectividad inmediatamente después del registro.
| Módulo / Función | Gratis | Inicial | Profesional | Empresarial |
|---|---|---|---|---|
| Facturación e-CF (DGII) | ✓ | ✓ | ✓ | ✓ |
| Inventario | ✓ | ✓ | ✓ | ✓ |
| Ajuste de inventario por lote | - | ✓ | ✓ | ✓ |
| Punto de venta (POS) | ✓ | ✓ | ✓ | ✓ |
| Tareas (Kanban) | - | ✓ | ✓ | ✓ |
| Comisiones de ventas | - | ✓ | ✓ | ✓ |
| Contabilidad de doble entrada | - | - | ✓ | ✓ |
| Reportes avanzados | - | - | ✓ | ✓ |
| Webhooks salientes | - | ✓ | ✓ | ✓ |
| Herramientas de datos | - | - | ✓ | ✓ |
| Exportación XLSX | - | - | ✓ | ✓ |
| Copias de respaldo | - | - | ✓ | ✓ |
| Acceso a API | - | - | ✓ | ✓ |
| E-commerce | - | - | - | ✓ |
Paso 1 - Ir a la configuración de webhooks
- Desde el menú principal de Mosce ERP, ve a Configuración → Integraciones → Webhooks.
- Haz clic en Nuevo webhook.
Paso 2 - Configurar la URL del endpoint
- En el campo URL del endpoint, ingresa la URL HTTPS de tu servidor receptor.
- Mosce ERP valida que la URL comience con
https://. Las URLs que resuelvan a IPs privadas o de loopback son rechazadas por razones de seguridad. - Opcionalmente, agrega un nombre descriptivo para identificar el webhook en el listado (por ejemplo: "Producción - ERP", "Staging - pruebas").
Paso 3 - Seleccionar los tipos de evento
Mosce ERP tiene un catálogo de más de 40 eventos organizados por categoría:
| Categoría | Ejemplos de eventos |
|---|---|
| Ventas | invoice.created, invoice.paid, invoice.overdue, order.created, quote.accepted |
| Compras | purchase_invoice.created, purchase_order.received |
| Pagos | payment.created, payment.deleted |
| Inventario | stock_movement.created, low_stock.triggered |
| POS | pos_session.opened, pos_session.closed |
| Clientes | customer.created, customer.updated |
| Fiscal | fiscal_document.submitted, fiscal_document.accepted, fiscal_document.rejected |
| Backups | backup.completed, backup.failed |
| Cuenta | plan.upgraded, usage_limit.reached |
| Herramientas de datos | data.export.completed, data.import.completed |
Los eventos de Herramientas de datos se entregan cuando un trabajo de exportación o importación asíncrono alcanza su estado final (completado, fallido o cancelado). El payload incluye una URL firmada válida por 60 minutos: downloadUrl para exportaciones y errorReportUrl para importaciones con filas inválidas. Si la URL expira, tu integración puede volver a generarla con un GET al endpoint del trabajo.
Selecciona solo los eventos que tu sistema necesita. Suscribirte a eventos innecesarios aumenta el volumen de entregas sin beneficio.
Paso 4 - Guardar y copiar el secreto
Al guardar el webhook por primera vez, Mosce ERP genera un secreto de firma único para este endpoint. El secreto se muestra una sola vez - cópialo y guárdalo de inmediato en tu gestor de contraseñas o en las variables de entorno de tu servidor.
El secreto de firma no se puede recuperar después de cerrar el diálogo. Si lo pierdes, deberás rotarlo desde la pantalla de administración del webhook. Ver Seguridad y verificación de firma.
Paso 5 - Verificar la conectividad
Después de guardar el webhook, usa el botón Probar endpoint para enviar un evento de prueba a tu servidor y verificar que la conexión funciona correctamente. El resultado muestra el código de respuesta HTTP y la latencia en milisegundos.
Ver Probar un webhook para el detalle completo del flujo de prueba.
Modificar o eliminar un webhook
- Editar: haz clic en el webhook en el listado y modifica la URL, el nombre o las suscripciones de eventos. Los cambios aplican de inmediato.
- Pausar: puedes desactivar temporalmente un webhook sin eliminarlo. Las entregas se omiten mientras está pausado.
- Eliminar: al eliminar un webhook, todos los registros de entregas asociados se borran también.
Errores comunes
| Síntoma | Causa probable | Solución |
|---|---|---|
| La URL es rechazada al guardar | La URL usa http:// o resuelve a una IP privada | Cambia a una URL https:// con un nombre de dominio público |
| El webhook queda en estado "Deshabilitado" | Se acumularon entregas fallidas consecutivas | Ver Confiabilidad y reintentos para el proceso de rehabilitación |
| No recibo eventos aunque el webhook está activo | El evento no está en la lista de suscripciones | Edita el webhook y agrega el tipo de evento correspondiente |
| El secreto desapareció | Solo se muestra una vez al crear o rotar | Rota el secreto desde la pantalla del webhook y copia el nuevo inmediatamente |
Preguntas frecuentes
¿Cuántos webhooks puedo tener?
El número máximo de endpoints de webhook depende de tu plan. Consulta Facturación y suscripción o la página de precios para ver el límite de tu plan.
¿Puedo tener el mismo evento en más de un webhook?
Sí. Puedes tener múltiples endpoints suscritos al mismo evento. Mosce ERP entrega el evento a todos los endpoints activos suscritos.
¿Las entregas de webhooks cuentan para mi cuota mensual?
El primer intento de delivery de cada evento cuenta hacia tu límite mensual de entregas de webhooks. Los reintentos automáticos por fallo no se contabilizan doble. Ver Límites de uso.
¿Qué pasa si mi servidor está caído cuando llega un evento?
Mosce ERP reintenta la entrega automáticamente hasta 10 veces durante 24 horas. Ver Confiabilidad y reintentos para el cronograma de reintentos.
Relacionados
- Seguridad y verificación de firma
- Confiabilidad y reintentos
- Probar un webhook
- Límites de uso por plan
- Facturación y suscripción
Última actualización: 2026-05-09
Configurar tu almacenamiento privado
Cómo crear y conectar un bucket S3-compatible privado para que Mosce ERP almacene los archivos sensibles que tu cuenta produce - copias de seguridad, exportaciones programadas, exportaciones asíncronas grandes, reportes de errores de importación y otros artefactos privados del tenant.
Seguridad y verificación de firma
Cómo verificar que los webhooks de Mosce ERP son auténticos usando la firma HMAC-SHA256, y cómo rotar el secreto de firma de forma segura.