Resumen del módulo de webhooks
Los webhooks envían eventos de Deskgram a una dirección que indiques: un CRM, un servicio de automatización o tu aplicación. Son notificaciones salientes de Deskgram. No configuran un webhook de Telegram Bot API ni crean un canal de órdenes entrantes para el programa.
Comprobado con el código el 24 de octubre de 2026.
Antes de empezar: Deskgram debe estar abierto y el receptor debe ser accesible desde ese equipo. Se utiliza POST con JSON. Las entregas interrumpidas no se recuperan automáticamente al reiniciar.
La configuración mediante la interfaz no requiere programar. Para desarrollar el receptor o usar HTTP local, consulta la referencia de API.
Configuración rápida
- Obtén la URL del webhook entrante en el sistema receptor y prepara su secreto o token, si lo necesita.
- Abre Ajustes → Integraciones en Deskgram.
- Pulsa Nuevo, escribe un nombre y la Webhook URL.
- En Qué acciones enviar, selecciona los eventos.
- En De qué módulos, deja todos o elige algunos.
- En Contenido de la solicitud, selecciona el formato. Para empezar, usa JSON estándar de Deskgram si el receptor lo admite.
- Añade el secreto y las cabeceras necesarias.
- Revisa Activar webhook después de guardar y pulsa Crear webhook.
- Pulsa Probar, abre el Historial y revisa la entrega.
- Realiza una acción real corta que corresponda al evento y verifica el resultado en el receptor.
Probar utiliza ajustes guardados. Si cambias URL, secreto, eventos o campos, guarda antes de probar. Puedes crear varios webhooks con distintas direcciones, suscripciones y formatos.
Conectar un CRM
Introduce la URL entrante del webhook del CRM, no su página principal ni su panel. Una dirección de un canal compatible con Deskgram podría ser:
https://crm.example.com/api/v1/channel-webhooks/deskgram/123El dominio y el número son ficticios. Usa los datos de tu CRM.
| Ajuste | Valor |
|---|---|
| Nombre | Algo reconocible, como “CRM: eventos de mensajes” |
| Webhook URL | Dirección entrante completa |
| Secreto CRM | Secreto de ese canal si se exige |
| Formato | JSON estándar para un canal Deskgram compatible |
| Módulo | spam_pm para eventos de sus mensajes |
| Eventos | Mensaje enviado, fallo de envío y respuesta del lead según el caso |
| Activación | Necesaria para entregas automáticas |
Deskgram reconoce rutas /channel-webhooks/deskgram/{id} y muestra el campo del secreto CRM. Lo envía mediante x-secret. El CRM proporciona dirección y secreto por separado: la URL no permite deducir el secreto.
Con otro CRM, revisa su JSON y autorización. Lead CRM no es un adaptador universal: los campos deben coincidir con el contrato del receptor.
En n8n, Make, Zapier o una API propia, copia la URL del paso receptor y configura los campos esperados. El flujo entrante debe estar activado y ser accesible.
Elegir eventos
| Evento | Cuándo aparece |
|---|---|
task.completed | Terminó el procesamiento de la tarea |
task.failed | La tarea llegó a un estado final de error |
task.cancelled | Se detuvo o canceló la tarea |
message.sent | Se registró un envío admitido en spam_pm |
message.failed | Se registró un fallo de entrega admitido en spam_pm |
lead.reply_received | Se registró una respuesta entrante en spam_pm |
Para transferir mensajes individuales al CRM, elige eventos de mensajes. Tarea completada por sí solo no genera una solicitud por cada mensaje.
El final de una tarea no demuestra que todas sus acciones fueran correctas; contadores y errores dependen del módulo. Omitir un destinatario o fallar al resolverlo no siempre produce message.failed. No hay un evento específico de omisiones.
Para respuestas de leads, Deskgram debe recibirlas mediante un manejador activo. Crear el webhook no activa escucha permanente ni garantiza recopilar respuestas después de la tarea.
Los botones Resultados de tareas, Todos los disponibles y Limpiar seleccionan, respectivamente, los tres eventos finales, los seis eventos o ninguno. Tras limpiar, selecciona lo necesario antes de guardar.
Filtro de módulos
El filtro decide de qué tareas se aceptan los eventos. Todos los módulos no restringe el origen; Seleccionar módulos limita a los elegidos.
Por ejemplo, task.completed con spampm es el final de una tarea de mensajes privados; message.sent con spampm es un mensaje individual de esa tarea.
Elegir un módulo no le añade eventos nuevos. Los eventos de mensajes y respuestas en tiempo real están integrados actualmente con spam_pm; elegir otro módulo no activa automáticamente ese comportamiento.
Elegir datos de la solicitud
| Formato | Finalidad |
|---|---|
| JSON estándar de Deskgram | Evento completo con objetos anidados de tarea, lead o mensaje |
| Resultado corto | Campos editables de estado, contacto, mensaje y error |
| Lead CRM | Campos planos editables de lead y mensaje |
| Esquema propio | Nombres de campos propios y fuentes elegidas |
El contenido depende del evento y la lista guardada. Revisa la vista previa y después los datos enviados en el detalle real.
Campos propios
En cada fila, escribe a la izquierda el campo esperado por el receptor, selecciona a la derecha la fuente y activa su interruptor.
Ejemplo hipotético:
| Campo del receptor | Fuente Deskgram |
|---|---|
contact.telegram_id | lead.telegramuserid |
contact.username | lead.username |
comment | message.text |
Un evento de mensaje podría producir:
{ "contact": { "telegram_id": "123456789", "username": "example_client" }, "comment": "¡Hola!"}El punto crea objetos anidados. Si falta un valor, el campo se omite. Un teléfono puede no estar disponible: el webhook no revela números ocultos.
Si eliminas o desactivas todos los campos, se envía {}, sin sustituirlo por el evento completo. La vista previa no contiene los datos reales de un futuro destinatario; la solicitud puede tener menos campos.
El constructor selecciona y renombra valores. No ejecuta JavaScript, cálculos, búsquedas en el CRM ni cadenas de solicitudes HTTP.
Ajustes adicionales
| Campo | Uso |
|---|---|
| Secreto de firma | El receptor pide un secreto compartido o HMAC |
| Headers JSON | Cabeceras adicionales, por ejemplo Authorization |
| Timeout, segundos | Espera de red; 15 por defecto, de 3 a 60 en la interfaz |
Ejemplo de cabeceras:
{ "Authorization": "Bearer YOUR_RECEIVER_TOKEN"}YOURRECEIVERTOKEN representa el token del receptor, no una licencia Deskgram.
Al editar desde la interfaz, dejar vacío el campo del secreto guardado conserva el anterior. No se vuelve a mostrar su valor. La API REST tiene reglas explícitas de borrado distintas.
Con secreto, se añaden x-secret, X-Deskgram-Webhook-Secret y X-Deskgram-Signature. La firma permite comprobar el cuerpo, pero el secreto también viaja en cabeceras: utiliza HTTPS y no publiques sus valores en logs. El ejemplo de verificación está en la referencia.
Probar la conexión
Probar envía webhook.test, incluso a un endpoint desactivado. Comprueba HTTP y el tratamiento de una solicitud de prueba; no inicia tareas Telegram.
No contiene task, lead, account ni message. Aplica el mapping actual: si solo elegiste fuentes de lead, puede enviar un objeto vacío. El receptor debe admitir pruebas expresamente. Un rechazo por falta de lead puede ser una validación comercial; consulta estado y respuesta.
Solo HTTP 200–299 se considera correcto. Un 302 no sirve: no se siguen redirecciones. Introduce la URL final.
HTTP 200 acredita aceptación HTTP, no que se haya creado un lead o mensaje. Comprueba la respuesta y el registro real en el CRM.
Historial y reintentos
El historial muestra entregas recientes. Puedes filtrar por receptor y estado y actualizar la lista.
| Estado | Significado |
|---|---|
pending | Registro creado, sin resultado final |
retrying | Falló un intento y se está repitiendo |
success | HTTP 200–299 recibido |
error | Intentos agotados o entrega terminada con error |
Los detalles incluyen JSON enviado, evento original en registros nuevos, respuesta, error, intentos y fechas. No son una traza completa de cada intercambio.
Intentos automáticos
Hasta tres por entrega, con pausas aproximadas de 2 y 4 segundos antes del segundo y tercero, sin contar espera de red. También se repiten respuestas 4xx y 5xx.
Conservan el mismo X-Deskgram-Delivery-Id. El receptor debería deduplicarlo dentro del ámbito de ese remitente para no repetir una acción completada.
Reintento manual
- Abre una entrega fallida.
- Corrige URL, secreto o campos si hace falta.
- Guarda.
- Vuelve a la entrega y pulsa Reintentar entrega.
- Comprueba el nuevo registro y el resultado externo.
Solo está disponible para error. Crea otra entrega con otro ID, conservando la original.
Los registros nuevos usan el evento original y mapping actual. Los antiguos sin evento original reenvían el JSON guardado sin volver a transformarlo. URL, secreto y cabeceras actuales se usan en ambos casos.
Si el receptor procesó pero se perdió su respuesta, el reintento puede duplicar acciones. Como el manual cambia de ID, el CRM necesita además deduplicación comercial.
Desactivar evita nuevos eventos automáticos, no cancela solicitudes en marcha. Probar y Reintentar explícitos pueden enviar desactivado. Borrar conserva historial, pero impide reintentos.
Escenarios prácticos
Transferir mensajes al CRM
Selecciona spampm y message.sent, message.failed, lead.replyreceived. Usa JSON estándar y secreto para un canal Deskgram compatible. Envía a tu cuenta de prueba, responde y comprueba ambas entregas y registros: así pruebas eventos reales aparte de la conexión.
Automatizar tras una tarea
Selecciona task.completed y el módulo. Usa JSON estándar o resultado corto. Añade task.failed y task.cancelled para manejar también fallos y cancelaciones.
Recibir en tu aplicación
Configura URL, campos y secreto. Acepta POST JSON, valida firma, almacena o encola de forma fiable y devuelve 2xx. Procesa trabajos largos aparte. Consulta el contrato HTTP y HMAC.
Resolver problemas
| Síntoma | Revisar |
|---|---|
| Sin registros nuevos | Guardado, activado, evento de mensaje, filtro spam_pm, historial actualizado |
| Solo final de tarea | Añadir eventos de mensaje |
| Sin respuesta del lead | Manejador activo recibió respuesta y evento seleccionado |
| Probar no disponible | Endpoint sin guardar o prueba en curso |
| HTTP 401/403 | Secreto, Authorization y permisos |
| HTTP 404 | URL completa, ruta y canal |
| HTTP 301/302 | URL final sin redirección |
| HTTP 400/422 del receptor | JSON enviado, respuesta y contrato |
| Éxito sin lead | Respuesta CRM; evento sin datos de creación |
| JSON vacío | Campos desactivados o fuentes ausentes |
| Formato antiguo | Ajustes sin guardar o falta source_payload en registro antiguo |
| Conexión/timeout | Acceso desde este equipo, DNS, certificado, red y espera |
| Retry no disponible | No error, endpoint borrado o retry en curso |
| Agente rechaza localhost/HTTP | MCP exige HTTPS público |
Gestión con un agente IA
Las herramientas MCP requieren permiso en Ajustes → MCP. Sus diferencias son:
- Creación predeterminada en dry-run, endpoint nuevo desactivado.
- Solo HTTPS público, sin localhost, LAN ni HTTP.
- Una acción real aplicable de crear, editar, activar, probar o repetir mantiene reglas protegidas para futuros envíos.
- Editar desde la interfaz o apagar MCP no elimina esas reglas.
- Las lecturas no revelan secreto guardado, valores de headers ni cuerpos completos.
Leer, dry-run, desactivar y borrar tienen reglas propias y no transfieren por sí solos un endpoint antiguo a la política. Consulta MCP.
Limitaciones
- Son avisos salientes, no órdenes remotas arbitrarias ni un canal permanente desde CRM.
- El historial no es una cola durable automática; cerrar el programa interrumpe sin reanudación automática.
- Solo POST JSON, sin GET, multipart ni cuerpo de texto arbitrario.
- No garantiza entrega única ni orden de eventos distintos.
- Los resultados dependen del módulo y pueden faltar campos.
- Puede enviar contactos, textos, parámetros y resultados al exterior. Elige receptor y campos teniendo eso en cuenta.