Webhooks
¿Qué son los Webhooks?
Los Webhooks son un mecanismo que permite a tu sistema recibir notificaciones automáticas y en tiempo real cada vez que ocurre un evento específico en el Helpdesk. En lugar de comprobar manualmente las actualizaciones, el sistema envía una solicitud HTTP a la URL que configures, con los detalles del evento.
Objetivo: sirve para que sepas al instante cuándo cambian casos o mensajes, sin tener que revisar manualmente ni esperar sincronizaciones.
Valor:
- Para los usuarios finales: facilita una integración fluida entre el Helpdesk y sistemas externos como CRMs, herramientas de informes o plataformas de notificación internas.
- Para la empresa: mejora la eficiencia al automatizar flujos de trabajo basados en eventos.
Alcance: el sistema de Webhooks forma parte del producto Helpdesk. No es una herramienta independiente, sino que está diseñado para mejorar la gestión de casos mediante integraciones externas.
Conceptos clave
Webhook: una solicitud HTTP POST enviada desde el Helpdesk a la URL configurada del cliente de Hubtype.
Evento: el disparador en el Helpdesk que activa el Webhook (por ejemplo, “Nuevo caso”, “Nuevo mensaje”).
Payload: el cuerpo JSON enviado con el Webhook, que contiene los datos relevantes del evento.
Cómo usarlo
Recorrido por la interfaz
1. Entra en la sección Webhooks en los ajustes del Helpdesk.
2. Configura la URL de destino: añade el endpoint en tu sistema que recibirá las notificaciones.
3. Elige los eventos a los que le quieres hacer seguimiento, seleccionando una o varias casillas:
- Nuevo caso: se activa cuando se crea un caso. El payload incluye los detalles del caso.
- Nuevo mensaje: se activa cuando se recibe un mensaje. El payload incluye los detalles del mensaje.
- Caso resuelto: se activa cuando un caso se marca como resuelto. El payload incluye los detalles del caso.
- Caso asignado a un agente: se activa cuando un caso se reasigna. El payload incluye los datos del agente anterior y del nuevo agente.
- Caso transferido a otra cola: se activa cuando un caso se mueve a otra cola.
4. Guarda tu configuración.
5. (Opcional) Usa el botón Test Webhook para enviar un evento de prueba y confirmar que tu sistema recibe la notificación correctamente.
Precondiciones
- Tener un endpoint activo que pueda aceptar solicitudes HTTP POST.
- El endpoint debe poder procesar JSON.
Postcondiciones
- Una vez configurado, el sistema enviará automáticamente una solicitud POST con los datos del evento a la URL especificada cada vez que ocurra un evento seleccionado.
Ejemplos y casos de uso
Ejemplo 1: Sincronización con CRM
Un cliente conecta el Webhook a su CRM. Cuando un caso se reasigna a un nuevo agente, el CRM actualiza automáticamente el registro del cliente con la nueva asignación.
Ejemplo 2: Servicio de registro
Un cliente conecta el Webhook a un servicio de logging. Quiere registrar en sus sistemas cuándo se crea un nuevo caso.
Buenas prácticas
Qué hacer
- Utiliza siempre un endpoint seguro (HTTPS).
- Registra todos los eventos recibidos para hacer seguimiento y depuración.
- Emplea correctamente los códigos de estado HTTP: devuelve 200 OK para confirmar la entrega exitosa.
- Usa el botón Test Webhook antes de ponerlo en producción.
Qué no hacer
- No configures una URL inactiva o incapaz de procesar JSON.
- No selecciones eventos innecesarios, ya que podrían sobrecargar tu sistema receptor.
Payloads JSON de Webhook
A continuación tienes unos ejemplos de los payloads JSON que se envían a tu Webhook, según el tipo de evento.
Nuevo mensaje
{
"action": "new_message",
"data": {
"message": {
"id": "msg_12345",
"type": "text",
"action": "message_sent_by_enduser",
"agent": null,
"queue_id": "queue_001",
"chat_id": "chat_123",
"provider": "webchat",
"chat_provider_id": "provider_chat_456",
"text": "Hello, I need help with my account",
"created_at": "2025-09-01T10:00:00Z",
"case_id": "case_789",
"extra_data": {
"country": "US",
"language": "en",
"conversation_id": "conv_001"
}
}
}
}
Caso resuelto
{
"action": "case_resolved",
"data": {
"case": {
"id": "case_789",
"status": "status_resolved",
"created_at": "2025-09-01T09:00:00Z",
"resolved_at": "2025-09-01T09:30:00Z",
"assigned_to": {
"id": "agent_123",
"email": "agent@example.com"
},
"resolved_by": {
"id": "agent_123",
"email": "agent@example.com"
},
"queue_id": "queue_001"
}
}
}
Nuevo caso
{
"action": "new_case",
"data": {
"case": {
"id": "case_101",
"status": "status_open",
"created_at": "2025-09-01T08:45:00Z",
"queue_id": "queue_002",
"assigned_to": {
"id": "agent_456",
"email": "support@example.com",
"first_name": "John",
"last_name": "Doe"
}
}
}
}
Caso asignado
{
"action": "case_assigned",
"data": {
"prev_agent": {
"id": "agent_123",
"email": "agent.old@example.com"
},
"next_agent": {
"id": "agent_789",
"email": "agent.new@example.com",
"role": "role_support"
},
"case": {
"id": "case_101",
"status": "status_attending",
"created_at": "2025-09-01T08:45:00Z"
}
}
}
Caso transferido a otra cola
{
"action": "case_transferred",
"data": {
"prev_queue": {
"id": "queue_001",
"name": "Support - English",
"project": "Customer Support Project"
},
"next_queue": {
"id": "queue_002",
"name": "Support - German",
"project": "Customer Support Project"
},
"prev_user": null,
"next_user": null,
"executor_user": {
"id": "admin_001",
"name": "Admin User",
"pic": null
},
"case": {
"id": "case_202",
"status": "status_waiting",
"created_at": "2025-09-01T09:05:00Z",
"resolved_at": null,
"assigned_to": null,
"resolved_by": null,
"queue_id": "queue_002",
"queue_prioritisation": "medium",
"project_id": "project_123",
"chat": {
"id": "chat_555",
"name": "Webchat User",
"provider": "webchat",
"is_online": true
},
"last_message": [
{
"id": "msg_987",
"type": "text",
"action": "message_sent_by_enduser",
"text": "I need help with my order",
"created_at": "2025-09-01T09:04:00Z",
"extra_data": {
"email": "customer@example.com",
"country": "DE",
"language": "de",
"issueDescription": "Order not delivered"
}
}
],
"unread_messages": 1,
"extra_data": {
"language": "de",
"position_in_queue": 1,
"position_in_queue_notified_at": "2025-09-01T09:05:30Z"
}
}
}
}