Notificaciones Externas

¿Qué son y para qué sirven?

Una Notificación Externa es la configuración de un aviso automático: eliges un Objeto (por ejemplo, Facturas a Crédito o Artículos), un Evento (Después de Crear, Editar, Borrar, Anular, Autorizar, Rechazar o Actualizar Existencia) y una URL de destino. A partir de ahí, cada vez que ese evento ocurra sobre ese tipo de documento en tu empresa, AdmCloud envía en segundo plano una petición POST con un cuerpo en formato JSON a esa URL, sin detener ni retrasar la transacción que la disparó.

Se usa principalmente para integrar AdmCloud con otros sistemas en tiempo casi real: por ejemplo, avisarle a tu bodega externa cuando se crea una factura, actualizar un tablero propio cuando cambia la existencia de un artículo, o disparar un flujo en una herramienta de automatización (Zapier, Make, un endpoint propio, etc.) cuando se registra un recibo de ingreso o se anula un documento. De momento el único tipo de notificación disponible es Webhook; el campo Tipo está pensado para escalar en el futuro a otros canales (correo, SMS, etc.).

Pantallas del área

Cómo crear una notificación externa paso a paso

1. Abre el listado y pulsa Nuevo. Necesitas el nivel de "agregar" del permiso "Notificaciones Externas".
2. Elige el Objeto que quieres monitorear, del catálogo de documentos que admiten notificaciones externas (ver la lista más abajo). El tipo queda fijo en Webhook, el único disponible por ahora.
3. Escribe un Nombre descriptivo que te ayude a identificar la notificación en el listado (por ejemplo, "Avisar a bodega al crear factura").
4. Elige el Evento que la debe disparar: Después de Crear, Editar, Borrar, Anular, Autorizar, Rechazar o Actualizar Existencia. Los dos de autorización solo aplican a los objetos con flujo de aprobación, y Actualizar Existencia solo a Artículos.
5. Captura la URL del sistema externo que va a recibir el aviso. Debe ser una URL completa y válida (con su protocolo, por ejemplo https://...).
6. Captura el Secreto (opcional, mínimo 16 caracteres) si quieres que las entregas viajen firmadas y el sistema receptor pueda verificar que el aviso salió de AdmCloud. Tiene que ser el mismo valor que configures del otro lado. Si lo dejas vacío, las llamadas se envían sin firma.
7. Elige el Dueño (usuario responsable de la configuración) y, si quieres que solo esa persona pueda ver o editar esta notificación, marca Protegida.
8. Verifica que esté Habilitada y agrega notas si necesitas dejar contexto para otros usuarios.
9. Guarda. Desde ese momento, cada vez que ocurra el evento elegido sobre el objeto elegido, AdmCloud llamará a la URL en segundo plano.

Objetos que admiten notificaciones externas

Hoy puedes crear notificaciones externas sobre estos documentos y catálogos:

• Compras: Informes de Gastos, Órdenes de Compra, Facturas de Proveedor a Crédito, Notas de Crédito a Proveedores, Notas de Débito a Proveedores, Recepciones de Proveedor, Retenciones de Impuestos a Proveedores.
• Ventas: Cotizaciones, Pedidos, Facturas al Contado, Facturas a Crédito, Recibos de Ingreso, Devoluciones de Efectivo, Notas de Crédito a Clientes, Notas de Débito a Clientes.
• CRM: Oportunidades, Prospectos.
• Inventario: Artículos, Servicios, Guías de Remisión.
• Relacionados: Clientes, Proveedores, Empleados.
• Bancos: Pagos a Proveedores.
• Servicio al Cliente: Solicitudes de Servicio, Órdenes de Trabajo.

Si eliges un objeto que no está en esta lista, AdmCloud rechaza el guardado indicándote que ese objeto no admite Notificaciones Externas.

Capacidades principales

• Aviso casi en tiempo real: la llamada al webhook se hace en segundo plano justo después de guardar, sin que el usuario tenga que esperar ni notar ninguna diferencia al grabar su documento.
• Cuerpo en JSON con el evento, el objeto y el identificador del registro (o de varios registros, en el caso de Actualizar Existencia), para que tu sistema externo sepa exactamente qué cambió y pueda ir a buscar el detalle si lo necesita.
• Varias notificaciones por objeto/evento: puedes registrar más de una URL para el mismo objeto y evento si necesitas avisar a distintos sistemas.
• Activar/desactivar sin borrar: desmarca Habilitada para pausar temporalmente un aviso sin perder su configuración.
• Configuración protegida por dueño: si marcas una notificación como Protegida, solo su dueño (o un usuario de soporte de AdmCloud) puede consultarla o editarla.
• Entrega firmada: si capturas un Secreto, cada llamada lleva el encabezado X-AdmCloud-Signature con la firma HMAC-SHA256 del cuerpo, para que tu sistema pueda comprobar que la petición salió de AdmCloud y que nadie modificó el contenido en el camino. Si no capturas un secreto, la llamada se envía sin firma.
• Reintentos automáticos: si tu sistema no responde o devuelve un error del servidor (código 500 o superior), AdmCloud reintenta hasta 3 veces, esperando 1 y 2 segundos. Si el rechazo es del lado de la petición (códigos 400 a 499) no se reintenta, porque repetirla daría el mismo resultado.
• Registro de entregas: AdmCloud guarda cada entrega (exitosa o no) con el cuerpo que envió, la respuesta que recibió y cuántos intentos hizo. Si un aviso no llegó, soporte de AdmCloud puede revisar ese registro para decirte exactamente qué respondió tu sistema.

Campos clave

Validaciones al guardar

• Objeto requerido, y debe ser uno de los objetos que admiten Notificaciones Externas; si eliges otro, AdmCloud te lo indica y no permite guardar.
• Nombre requerido.
• Tipo requerido (queda fijo en Webhook).
• URL requerida, y debe ser una URL absoluta válida (con su protocolo, por ejemplo https://...); si el formato no es correcto, no se permite guardar.
• Dueño requerido.
• Secreto de al menos 16 caracteres, si decides capturar uno (es opcional). Un secreto corto se puede adivinar y entonces la firma deja de servir de garantía. Los espacios al inicio y al final se eliminan, porque un espacio pegado al copiar rompería la verificación en tu sistema sin dejar ninguna pista.
• No se permite duplicar la misma combinación de Objeto, Evento y URL en dos notificaciones distintas.

Disponibilidad, plan y activación

• Esta función requiere un plan con acceso a API, disponible desde el plan Basic en adelante (Basic, Standard, Premium, Premium Plus y sus variantes, Enterprise). No está disponible en los planes Billing ni Start.
• Además del plan, tu cuenta necesita tener habilitada la función de Notificaciones Externas. Si tu plan la incluye pero no ves esta pantalla ni el permiso correspondiente en los Grupos de Usuarios, contacta a soporte de AdmCloud para activarla.
• El acceso a la pantalla se controla con el permiso "Notificaciones Externas" del grupo de usuarios, con niveles separados para consultar, agregar, editar y eliminar.

Payload que se envía (formato JSON)

Cada llamada es un POST con encabezado Content-Type: application/json y un cuerpo JSON compacto (sin indentación), con las propiedades en PascalCase tal cual están declaradas internamente en AdmCloud. No es el mismo formato (camelCase/minúsculas) que usan las respuestas de la API REST descritas en la Guía de la API Web; si tu integración ya consume la API, no asumas que el cuerpo del webhook usa la misma convención de nombres.

Eventos normales (Crear, Editar, Borrar, Anular, Autorizar, Rechazar)

{
  "EventID": 0,
  "EventName": "Después de Crear",
  "ObjectID": 40030,
  "ObjectName": "Facturas a Crédito",
  "RecordID": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

RecordID es el identificador (GUID) del registro que disparó el evento: el mismo valor que usarías para consultar el documento completo por la API de AdmCloud. El payload del webhook no incluye el documento en sí (líneas, totales, cliente, etc.), solo lo mínimo para identificar qué cambió; si necesitas el detalle, tu sistema debe ir a buscarlo con ese RecordID.

Evento "Después de Actualizar Existencia"

Este evento tiene una forma distinta: en vez de RecordID trae RecordIDs, una lista, porque una sola transacción (una recepción, un traslado entre bodegas, un ajuste de inventario, una producción, etc.) puede afectar la existencia de varios artículos a la vez. ObjectID siempre corresponde a Artículos, sin importar qué transacción disparó el cambio de existencia.

{
  "EventID": 3,
  "EventName": "Después de Actualizar Existencia",
  "ObjectID": 130060,
  "ObjectName": "Artículos",
  "RecordIDs": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "a1b2c3d4-1234-4a1b-9c3d-4e5f6a7b8c9d"
  ]
}

Códigos de EventID

Códigos de ObjectID

ObjectID es el código numérico interno con el que AdmCloud identifica cada tipo de documento; es el mismo catálogo que usa toda la aplicación, no algo exclusivo de Notificaciones Externas. Estos son los códigos de los objetos que hoy admiten notificaciones externas:

Encabezados y verificación de la firma

• Content-Type: application/json en toda entrega.
• X-AdmCloud-Signature: solo viaja cuando la notificación tiene un Secreto configurado. Si no hay Secreto, el encabezado simplemente no se envía (no llega vacío ni con una firma inválida).
• Tiempo de espera: AdmCloud espera hasta 30 segundos la respuesta de tu sistema en cada intento. Si no respondes a tiempo, se trata igual que una falla de red (ver Reintentos automáticos abajo).

Para verificar que un aviso realmente vino de AdmCloud y no fue alterado en el camino:

1. Calcula HMAC-SHA256 sobre los bytes UTF-8 del cuerpo exactamente como lo recibiste (el texto crudo de la petición POST), usando como llave el mismo Secreto que capturaste al configurar la notificación. No vuelvas a serializar el JSON tú mismo antes de firmarlo: reordenar propiedades o cambiar espacios cambia el resultado y la firma no coincidirá aunque el contenido sea "el mismo".
2. Convierte el resultado del HMAC a hexadecimal en minúsculas.
3. Compara ese valor contra el encabezado X-AdmCloud-Signature quitándole el prefijo sha256= (por ejemplo, sha256=f7bc83f4...).

Consejos y errores comunes