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 . 5 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, -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 la pestaña 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 regenerarla. Si la regeneras, las entregas siguientes se firman con la nueva y tu servidor tiene que actualizarla.
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-Timestampstringobligatorio
- Instante de emisión en milisegundos Unix. 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 |
| 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 desde la API del panel
La configuración y el historial de entregas también se pueden gestionar con la API del panel. Estos endpoints no aceptan X-Api-Key: se llaman con la sesión de una persona (Authorization: Bearer) que tenga el aplicativo Integraciones en su plan y los permisos «Ver aplicaciones externas» (lecturas) o «Editar aplicaciones externas» (cambios).
/api/integrations/apps/:id/webhookCambia la dirección de avisos, los activa o desactiva y fija la lista de eventos (webhookUrl, webhookEnabled, webhookEvents).
/api/integrations/apps/:id/webhook/testEnvía un aviso de prueba firmado a la dirección configurada. No queda en el historial ni se reintenta.
/api/integrations/apps/:id/webhook-deliveriesLista el historial de entregas de la aplicación, con filtros por estado y por evento.
/api/integrations/apps/:id/webhook-deliveries/:deliveryIdDevuelve el detalle de una entrega: contenido enviado, respuesta de tu servidor y próximo intento.
/api/integrations/apps/:id/webhook-deliveries/:deliveryId/retryVuelve a encolar una entrega que no llegó. Responde 204 cuando queda encolada.
/api/integrations/apps/:id/metrics/webhooksTasa de éxito de las entregas en un periodo (por defecto, las últimas 24 horas).
Siguiente paso
Prepara tu servidor para recibirlos con Firma HMAC de los avisos.
Ponlo en práctica
Lo encontrarás en Aplicaciones externas. Para abrirlo, entra con tu cuenta de UTILIA OS.