Avisos a tu servidor: visión general
Qué son los avisos que UTILIA OS envía a tu servidor, cómo se configuran, qué cabeceras traen, cómo se reparten y qué eventos existen.
Actualizado el . 6 min de lectura
Incluido en todos los planes. Ver precios
Los avisos a tu servidor (webhooks) son peticiones POST que UTILIA OS envía a una dirección tuya cada vez que pasa algo que te interesa: un ticket recibe respuesta, se cobra una factura, un lead se cualifica. Así tu sistema se entera al momento, sin tener que preguntar a la API cada poco.
Cada aviso va firmado con la clave de firma de tu aplicación, se reintenta si tu servidor falla y lleva un identificador de entrega estable para que puedas descartar duplicados.
Un aviso, de principio a fin
Participan: UTILIA OS, Tu servidor.
Nota en UTILIA OS:
Pasa algo a lo que tu aplicación está suscrita, por ejemplo una respuesta en un ticket.De UTILIA OS a Tu servidor:
POST a tu dirección de avisos
Cuerpo JSON y cabeceras X-Utilia-Signature, X-Utilia-Webhook-Signatures, -Timestamp, -Event, -Delivery-Id y -Schema-Version.Nota en Tu servidor:
Comprueba la firma y la marca de tiempo, y descarta el aviso si ya procesó ese Delivery-Id.De Tu servidor a UTILIA OS:
2xx en menos de 30 segundos (respuesta)
La entrega queda como entregada.
Cómo se configuran
Indica la dirección
En la ficha de tu aplicación externa, abre Configuración › Avisos a tu servidor, activa Enviar avisos y escribe en Dirección de tu servidor la dirección
https://que los recibirá. Por seguridad, no se admiten direcciones de redes privadas ni internas.Elige los eventos
Marca los eventos que quieres recibir. Tu aplicación solo recibe los que marques: los demás no generan ninguna entrega. La lista que ves ya está recortada por el plan de tu organización: los eventos de un aplicativo o de una capacidad que no tienes contratados no aparecen.
Prueba la entrega
Guarda los cambios y pulsa Probar: UTILIA OS envía un aviso de prueba a la dirección guardada y te dice qué ha contestado tu servidor. Va firmado exactamente igual que los reales, con las mismas cabeceras, así que si tu servidor lo acepta, aceptará los reales.
La clave de firma se muestra una sola vez, al crear la aplicación o al renovarla. Al renovarla eliges cuánto tiempo sigue valiendo la anterior: durante ese periodo de transición cada aviso lleva las dos firmas, así que tu servidor cambia de clave sin cortes. Lo explicamos en Firma HMAC de los avisos.
Qué recibe tu servidor
Cada aviso es un JSON con esta forma:
{
"event": "TICKET_REPLIED",
"timestamp": "2026-10-08T10:00:00.000Z",
"app": { "id": "app_xxxxxxxx", "slug": "mi-aplicacion" },
"data": { "...": "datos del evento" },
"meta": { "schemaVersion": "2026-05" }
}Y viaja con estas cabeceras:
- X-Utilia-Signaturestringobligatorio
- Firma HMAC-SHA256 de la cadena
${timestamp}.${cuerpo}con la clave de firma de la aplicación, con el prefijosha256=. Si la clave no se puede recuperar, la entrega no sale: nunca recibirás un aviso sin firma. - X-Utilia-Webhook-Signaturesstringobligatorio
- Lista de firmas separadas por comas, la de la clave vigente primero. Durante el periodo de transición de una renovación lleva también la firma de la clave anterior. Se explica en Firma HMAC de los avisos.
- X-Utilia-Timestampstringobligatorio
- Instante en que sale ese intento, en milisegundos Unix: cambia en cada reintento, mientras que el timestamp del cuerpo es el de cuando se generó el aviso. Forma parte de lo firmado y sirve para rechazar avisos reenviados tiempo después.
- X-Utilia-Eventstringobligatorio
- Nombre del evento, el mismo que el campo event del cuerpo.
- X-Utilia-Delivery-Idstringobligatorio
- Identificador de la entrega. Es el mismo en todos los reintentos: úsalo para no procesar dos veces el mismo aviso.
- X-Utilia-Schema-Versionstringobligatorio
- Versión de la forma del contenido (2026-05; 2026-07 en los eventos de chat). Te permite detectar un cambio de estructura sin leer el cuerpo.
Para aceptar un aviso, tu servidor tiene que comprobar la firma sobre el cuerpo tal como llegó, rechazar los que tengan una marca de tiempo de hace más de cinco minutos y descartar los identificadores de entrega que ya haya procesado. Los pasos y el código en Node.js y Python están en Firma HMAC de los avisos.
Tu servidor debe responder con un código 2xx en menos de 30 segundos. Qué pasa si no lo hace se explica en Entregas y reintentos de los avisos.
Avisos dirigidos y avisos por difusión
Quién recibe cada aviso
Solo la aplicación dueña
Dirigidos
Todas las suscritas
Por difusión
En los eventos de contactos, leads y clientes del CRM, la aplicación que provocó el cambio no recibe su propio aviso, para evitar bucles.
Eventos disponibles
| Área | Eventos | Qué necesita el plan |
|---|---|---|
| Tickets de soporte | TICKET_CREATED, TICKET_REPLIED, TICKET_RESOLVED, TICKET_CLOSED, TICKET_CONVERTED, TICKET_ASSIGNED, TICKET_REOPENED | Tickets de soporte, con «Tickets propios» |
| Usuarios externos | USER_CREATED | Integraciones |
| Archivos | FILE_UPLOADED | Gestor de archivos |
| Errores de tu aplicación | ERROR_REPORTED, ERROR_RESOLVED, ERROR_REOPENED, ERROR_SILENCED, ERROR_LINKED_TO_TICKET, ERROR_LINKED_TO_ISSUE | Integraciones |
| Salud de tu aplicación | APP_HEALTH_CHANGED | Integraciones |
| Instalaciones del catálogo | APP_INSTALLED, APP_UNINSTALLED, APP_ACCESS_CHANGED, APP_SUSPENDED, APP_REINSTATED y, en las de pago, los doce APP_SUBSCRIPTION_*. Solo para aplicaciones del catálogo; llegan solos, sin marcarlos | Integraciones (APP_UNINSTALLED, APP_SUSPENDED, APP_SUBSCRIPTION_ENDED y APP_SUBSCRIPTION_PAUSED llegan aunque falte) |
| Presupuestos | 28 eventos: ciclo del presupuesto, comentarios, firma electrónica e imágenes | CRM |
| Facturación | INVOICE_CREATED, INVOICE_SENT, INVOICE_PAID, INVOICE_PARTIALLY_PAID, INVOICE_PAYMENT_FAILED, INVOICE_OVERDUE, INVOICE_CANCELLED, INVOICE_REFUNDED, INVOICE_REFUND_CANCELLED, INVOICE_RECTIFIED, INVOICE_RECTIFICATION_CREATED, INVOICE_RECTIFICATION_METADATA_UPDATED | Finanzas |
| Métodos de pago | PAYMENT_METHOD_ADDED, PAYMENT_METHOD_REMOVED, PAYMENT_METHOD_EXPIRING | Finanzas y Pagos con tarjeta (Stripe) |
| Autorizaciones de cobro | PAYMENT_AUTHORIZATION_GRANTED, PAYMENT_AUTHORIZATION_REVOKED, PAYMENT_AUTHORIZATION_CONSUMED | Finanzas y Pagos con tarjeta (Stripe) |
| Suscripciones | SUBSCRIPTION_CREATED, SUBSCRIPTION_UPDATED, SUBSCRIPTION_PAUSED, SUBSCRIPTION_RESUMED, SUBSCRIPTION_CANCELLED, SUBSCRIPTION_COMPLETED, SUBSCRIPTION_INVOICE_GENERATED, SUBSCRIPTION_PAYMENT_AUTHORIZATION_PENDING | Finanzas, con «Cobros recurrentes» |
| Cobros programados | CHARGE_SCHEDULED, CHARGE_STARTED, CHARGE_SUCCEEDED, CHARGE_FAILED, CHARGE_REQUIRES_ACTION, CHARGE_RETRY_SCHEDULED, CHARGE_RETRIES_EXHAUSTED, CHARGE_CANCELLED | Finanzas y Pagos con tarjeta (Stripe), con «Cobro automático de facturas» |
| Contactos del CRM | CONTACT_CREATED, CONTACT_UPDATED, CONTACT_DELETED, CONTACT_OPTED_OUT, CONTACT_OPTED_IN | CRM |
| Leads del CRM | LEAD_CREATED, LEAD_UPDATED, LEAD_QUALIFIED, LEAD_DISQUALIFIED, LEAD_CONVERTED, LEAD_SCORE_UPDATED | CRM, con «Leads» |
| Clientes del CRM | CLIENT_CREATED, CLIENT_UPDATED, CLIENT_DEACTIVATED, CLIENT_REACTIVATED, CLIENT_FISCAL_DATA_UPDATED, CLIENT_LINKED_TO_GROUP, CLIENT_UNLINKED_FROM_GROUP | CRM (los dos de grupos, con «Grupos empresariales») |
| Plataforma de chat | 14 eventos de mensajes, canales, miembros, menciones y agentes | Chat (los de agentes, con «Agentes de canal») |
Si la organización deja de tener el aplicativo o la capacidad que un evento necesita, ese evento deja de emitirse aunque siga marcado en tu configuración.
El contenido de cada evento, con ejemplos, está en Avisos: contenido y catálogo de eventos. Los del chat se documentan aparte, en Webhooks de chat.
Gestionar los avisos sin abrir la ficha
La dirección, los eventos, el aviso de prueba y el historial de entregas se gestionan en la ficha de la aplicación, en Configuración › Avisos a tu servidor. La clave de la aplicación no los abre: es la credencial que recibe los avisos, no la que los configura.
Si quieres automatizarlo, la herramienta MCP integrations del servidor de Gestión de proyectos (utilia-work) tiene las mismas acciones (apps_webhooks_get_config, apps_webhooks_update_config, apps_webhooks_test, apps_webhooks_list_deliveries, apps_webhooks_get_delivery y apps_webhooks_retry_delivery), con los permisos de la persona que autoriza el acceso. Está en la Referencia de herramientas MCP. Para probar tu receptor con una muestra de un evento del catálogo, marcada con livemode: false y meta.test: true, sigue Probar los avisos a tu servidor.
Siguiente paso
Prepara tu servidor para recibirlos con Firma HMAC de los avisos.
Ponlo en práctica
Lo encontrarás en Creadas por tu empresa. Para abrirlo, entra con tu cuenta de UTILIA OS.