Webhook de notificaciones
Configura webhooks HTTP y Google Cloud Pub/Sub: destinos, eventos, reglas, autenticación, rotación de credenciales y verificación de recepción.
Conecta los eventos de Adereso Desk con tus sistemas mediante HTTP o Google Cloud Pub/Sub. Esta guía explica cómo configurar destinos, proteger las credenciales, definir reglas y verificar la recepción de los eventos.
Recorrido en video
El video muestra cómo se relacionan la configuración general, los destinos y las reglas. Las pantallas y ejemplos de esta guía explican los requisitos técnicos, la autenticación y la comprobación de la recepción en tu sistema.
Tiempo | Qué encontrarás |
00:06 | Interruptor general, destinos y reglas: qué configura cada bloque |
00:16 | Destino HTTP, Authorization y conservación del secreto al editar |
00:28 | Google Cloud Pub/Sub: tópico, cuenta de servicio y prueba de publicación |
00:40 | Eventos, condiciones y destinos de las reglas |
00:51 | Riesgo de HTTP sin autenticación y verificación del emisor |
01:04 | Rotación de credenciales y continuidad de configuraciones legadas |
01:18 | Configurar autenticación, definir reglas y verificar la recepción |
Después de verlo, sigue las pantallas de la guía y el checklist final para comprobar la recepción en tu sistema. Una prueba de conexión correcta no sustituye esa verificación.
Cómo leer esta guía
Sigue las pantallas en orden. En cada una se explica qué estás viendo, qué debes completar, qué acción guarda cambios y cómo verificar el resultado. Las URLs de ngrok, los nombres de proyectos y los IDs que aparecen en las imágenes pertenecen a pruebas: sustitúyelos por los recursos de tu organización; no copies esos destinos.
Los valores de las imágenes son ilustrativos. Guardar una regla no demuestra, por sí solo, que tu sistema haya recibido el evento: comprueba también los registros de tu receptor o consumidor.
Antes de abrir Desk
Responsable | Preparación necesaria | Resultado que debe tener listo |
Administrador de Desk | Acceso al establecimiento correcto y permisos para administrar integraciones | Poder abrir Webhook de notificaciones y guardar destinos/reglas |
Desarrollador HTTP | Receptor HTTPS, secreto y validación de Authorization | Endpoint que autentique antes de procesar JSON |
Administrador Google, si usas Pub/Sub | Tópico, cuenta dedicada y permiso Publisher sobre ese tópico | Nombre completo del tópico y JSON de la cuenta |
Responsable del consumidor Pub/Sub | Suscripción y aplicación consumidora | Poder recibir y confirmar los mensajes en Google |
El usuario que concede permisos en Google puede ser distinto de la cuenta de servicio utilizada por Desk. No necesitas entregar a Desk la cuenta personal del administrador.
Pantalla 1. Ubicarse y entender la configuración general
Abre Administración → Integraciones → Webhook de notificaciones → Configurar en el establecimiento donde quieres recibir eventos.
Zona de la captura | Qué significa | Qué debes hacer |
Bloque Webhooks, arriba | Interruptor global de envíos del establecimiento | Usa Activos/Pausados; el cambio se guarda inmediatamente |
Destinos, al centro | Sistemas externos a los que Desk puede enviar | Pulsa Agregar destino para configurar HTTP o Pub/Sub |
Reglas de envío, abajo | Evento, condiciones y acciones que deciden cuándo notificar | Crea una regla después de tener un destino |
Volver a integraciones | Navegación al catálogo | No sustituye los botones de guardado de los formularios |
Lee el estado completo de la imagen: el interruptor dice Activos, pero no existen destinos ni reglas. Por lo tanto, esa configuración todavía no enviará eventos de negocio.
Para una conexión nueva puedes mantener Webhooks pausado mientras completas destino y reglas, y activarlo al terminar. Si el establecimiento ya tiene integraciones funcionando, el interruptor afecta a todas sus reglas de webhook: no lo pauses como si fuera un control exclusivo del destino que estás editando.
Qué ocurre al cambiar el interruptor: espera a que termine el guardado. Durante la petición se bloquea el control; si falla, se restaura el estado anterior y aparece un error. Recarga la pantalla para comprobar el valor persistido. No hay un botón “Guardar configuración general” en esta vista moderna. Pausar no borra la configuración ni es un mecanismo para cancelar peticiones que ya están en tránsito.
Qué conecta esta integración
Desk envía eventos a tus sistemas cuando se cumple una regla. Puedes configurar varios destinos y reutilizarlos en distintas reglas. Hay dos transportes: HTTP y Google Cloud Pub/Sub. Pub/Sub no representa soporte genérico para RabbitMQ, Kafka, Amazon SQS u otras colas.
Evento en Desk → regla y condiciones → destino → tu receptor o consumidor. La entrega puede ser asíncrona; diseñar tu receptor para mensajes repetidos evita efectos duplicados.
Qué guarda cada control
Control | Qué modifica | Qué no hace |
Interruptor Webhooks | Activa o pausa los envíos del establecimiento y guarda inmediatamente | No borra destinos ni reglas |
Probar y agregar destino | Verifica la conexión y crea el destino si la prueba funciona | No crea una regla ni activa Webhooks |
Guardar destino HTTP | Actualiza formato y Authorization | No cambia las reglas ni genera un token |
Probar y guardar destino Pub/Sub con clave nueva | Verifica publicación antes de reemplazar la credencial | No cambia el tópico ni crea un consumidor |
Guardar regla | Guarda evento, condiciones y acciones hacia destinos concretos | No modifica credenciales ni activa la integración |
Un destino sin reglas no recibirá eventos de negocio por sí solo. La prueba de conexión es un evento técnico, no una ejecución completa de cada regla.
Elegir la autenticación
Destino | Credencial | Quién la prepara | Quién verifica |
HTTP con Authorization | Secreto compartido; por ejemplo, un valor completo Bearer TU_SECRETO | Tu equipo de desarrollo | Tu servidor receptor |
HTTP sin Authorization | Desk no adjunta credenciales de autenticación | No aplica | Requiere otro control de autenticación en el receptor; de lo contrario hay riesgo de suplantación |
Google Cloud Pub/Sub | JSON de cuenta de servicio autorizada | Administrador de tu proyecto Google | Google IAM al publicar |
HTTP sin autenticación es un riesgo de seguridad si el receptor público acepta eventos sin verificar al emisor: terceros podrían enviar notificaciones falsas y disparar procesos internos. HTTPS protege la comunicación, pero no demuestra que el emisor sea Desk. Recomendamos configurar Authorization y verificarlo antes de procesar el cuerpo. Si usas controles externos, deben ser evaluados por tu equipo de seguridad. La ausencia de esta cabecera no demuestra por sí sola que el receptor carezca de cualquier otro control.
Pantalla 2. Reconocer la opción HTTP sin autenticación
Elemento visible | Interpretación correcta |
Tipo de destino: HTTP | Desk llamará a la URL de tu receptor mediante POST |
URL del destino | Debe ser el endpoint de tu aplicación; no una página de login ni la URL de la consola de tu proveedor |
Versión del payload | El formato del mensaje que deberá entender tu receptor; no activa el sistema antiguo |
No enviar Authorization (riesgo de seguridad) | La petición no incluirá la credencial configurada por esta integración |
Recuadro amarillo | Explica el riesgo de aceptar peticiones sin verificar quién las envía |
Probar y agregar deshabilitado en la captura | Aún faltan datos válidos, como la URL; no significa que la advertencia obligue por sí sola a activar Authorization |
Qué debes hacer: para el flujo recomendado, cambia la autorización a Usar un token nuevo y sigue la pantalla 3. El aviso no añade autenticación a tu servidor: debes implementarla allí. Si tu arquitectura usa otro control, verifícalo con tu equipo antes de aceptar eventos sin esta cabecera.
No confundir: guardar con esta opción no crea un secreto ni hace que Desk genere una credencial más tarde. Si había un token guardado y desactivas su envío, se conserva para una reactivación explícita; no se revoca en tu infraestructura.
La advertencia corresponde a HTTP. Un destino Pub/Sub usa Google IAM y no debe interpretarse como anónimo por no utilizar una cabecera HTTP configurada en Desk.
HTTP: generar y configurar el secreto
- Implementa un endpoint HTTPS en tu infraestructura que reciba
POSTcon JSON. No uses un receptor público de pruebas para datos reales de clientes.
- Genera un secreto aleatorio en un equipo seguro. Ejemplo, para ejecutar por tu equipo:
python3 -c 'import secrets; print(secrets.token_urlsafe(32))'- Guarda el secreto en tu gestor de secretos. No uses una contraseña personal, un token de sesión de Desk ni una clave de usuario de la API de Desk.
- Configura tu receptor para aceptar el valor completo que usarás en la cabecera. Si eliges el esquema Bearer, el valor será
Bearer TU_SECRETO.
- En Desk, abre Administración → Integraciones → Webhook de notificaciones → Agregar destino → HTTP. Indica la URL, selecciona Usar un token nuevo y pega el valor completo en el campo de token. Desk envía ese valor exactamente; no añade automáticamente
Bearer.
- Pulsa Probar y agregar. El receptor debe aceptar también el evento técnico de prueba y devolver una respuesta satisfactoria.
- Crea y guarda una regla hacia ese destino, activa Webhooks y dispara un evento de negocio para verificar el procesamiento completo.
Pantalla 3. Completar el destino HTTP autenticado
Campo/control | Qué escribir o elegir | Qué ocurre al usarlo |
Tipo de destino | HTTP | Muestra URL y opciones de Authorization; no solicita una clave JSON de Google |
URL del destino | Por ejemplo, https://tu-receptor.example/webhook | Se usa como dirección de la prueba y de futuras notificaciones |
Versión del payload del destino | El formato acordado con tu receptor | Todas las reglas que apunten a este destino usarán ese formato |
Autorización del destino | Usar un token nuevo | Habilita el campo secreto |
Token nuevo | El valor completo, por ejemplo Bearer TU_SECRETO | Se envía exactamente como valor de la cabecera Authorization |
Probar y agregar | Después de completar y verificar los datos | Prueba el receptor y crea el destino si la conexión se acepta |
Cancelar | Si no quieres conservar este borrador | Cierra el editor; no crea el destino |
La URL y el token de esta captura son ejemplos; el campo secreto está oculto. Los caracteres de contraseña no permiten recuperar una credencial guardada.
Cuándo se habilita el botón: debe existir una URL válida no repetida y, si seleccionaste token nuevo, un valor de token no vacío. Para un destino ya guardado, la opción Usar el token guardado aparece únicamente si existe una credencial disponible. No necesitas volver a escribirla para conservarla.
Al probar: Desk envía un POST técnico. Tu endpoint debe validar también su Authorization y reconocer el payload de prueba descrito más adelante. Si rechaza la credencial, devuelve un error o no puede establecerse la conexión, se muestra el fallo y se conserva el borrador para corregirlo. Un mensaje de prueba aceptado no demuestra todavía que tu parser procese correctamente los eventos de negocio.
Pantalla 4. Leer el destino HTTP una vez guardado
Zona de la tarjeta | Qué debes interpretar |
Primera línea y ruta | Host y endpoint de recepción; no el nombre de una regla |
Payload 1.0.0 / 2.0.0 | Formato elegido para ese destino |
Con Authorization | Desk enviará la cabecera configurada; tu receptor sigue siendo responsable de validarla |
Sin autenticación · Riesgo | Desk no enviará esa credencial HTTP; revisa la seguridad del receptor |
Sin reglas de envío | Existe el destino, pero ninguna regla moderna lo referencia |
Usado en 1 regla / varias reglas | Número de reglas asociadas, no cantidad de entregas exitosas |
Editar | Cambia formato y autorización; no modifica la URL del destino existente |
Quitar | Solicita confirmación para eliminar el destino de Desk; revisa primero las reglas que lo usan |
Resultado esperado después de un alta: ves una nueva tarjeta. Si aún indica Sin reglas de envío, continúa a las pantallas 9–11. Guardar el destino no te suscribe automáticamente a eventos.
Para cambiar de URL debes crear otro destino y ajustar las reglas. Editar el formato o la credencial de uno existente afecta a todas las reglas que ya lo utilizan. Quitar la tarjeta no elimina tu endpoint ni los datos de tu aplicación.
No existe un intercambio inicial donde Desk genere un token y tu receptor lo confirme. Tu equipo configura el mismo secreto en los dos extremos. La respuesta HTTP confirma recepción; no aprovisiona ni renueva credenciales.
Pseudocódigo del receptor HTTP
import hmac
import os
def recibir_webhook(request):
esperado = os.environ.get("WEBHOOK_AUTHORIZATION", "")
if not esperado:
return respuesta(503) # Error de configuración: no aceptar anónimamente.
recibido = request.headers.get("Authorization", "")
if not hmac.compare_digest(recibido.encode(), esperado.encode()):
return respuesta(401)
evento = validar_json_y_esquema(request.body)
if evento.get("EVENT") == "test_event":
return respuesta(200)
guardar_en_cola_durable(evento)
return respuesta(200)Es pseudocódigo: adapta el parsing, límites de tamaño, validación y persistencia a tu framework. El ejemplo asume que WEBHOOK_AUTHORIZATION contiene el valor completo, incluido Bearer si lo configuraste así. Evita registrar el encabezado o el secreto. No devuelvas éxito antes de aceptar de forma durable un evento que necesitas conservar.
Desk envía conceptualmente:
POST https://tu-receptor.example/webhook
Content-Type: application/json
Authorization: Bearer TU_SECRETO
{ payload_del_evento }Este esquema usa un secreto estático compartido; no es una firma HMAC del payload ni incorpora protección de replay por sí mismo. No se documentan cabeceras de firma, desafíos de verificación o renovación OAuth que esta configuración no implementa. Evita ejecutar dos veces efectos irreversibles ante mensajes repetidos.
Rotación HTTP
Haz que tu receptor acepte temporalmente el secreto anterior y el nuevo; configura el nuevo valor en Desk, guarda y verifica una entrega. Después retira el anterior de tu servidor. La clave guardada no se muestra al editar. Desactivar Authorization deja de enviarla; no revoca por sí mismo el secreto en tu infraestructura.
Pub/Sub: preparar Google Cloud
Necesitas un proyecto, Pub/Sub habilitado y un tópico existente. Tu administrador de Google debe poder crear una cuenta de servicio, administrar su clave y conceder acceso al tópico. El consumidor necesita sus propios permisos, separados de los que entregas a Desk.
- En Google Cloud, crea una cuenta de servicio dedicada para publicación de eventos de Desk.
- En los permisos del tópico, añade esa cuenta con Pub/Sub Publisher (
roles/pubsub.publisher), limitado al tópico. No concedas Owner, Editor ni acceso a todo el proyecto para esta integración.
- Abre IAM y administración → Cuentas de servicio → tu cuenta → Claves → Agregar clave → Crear clave nueva → JSON. Descarga el archivo y protégelo como un secreto. Google proporciona la clave privada al crearla; no la pegues en tickets, chats ni repositorios.
- Copia el nombre completo del tópico:
projects/TU_PROYECTO/topics/TU_TOPICO.
Referencia oficial: crear claves de cuentas de servicio, roles y acceso por recurso en Pub/Sub.
Google recomienda evitar claves administradas por usuarios cuando existe una alternativa adecuada. Este formulario actualmente acepta JSON de cuenta de servicio; no implementa una conexión federada ni Workload Identity Federation. Si la política de tu organización impide crear claves, no la desactives para seguir la guía: consulta con tu equipo de seguridad y Adereso para evaluar una alternativa. Buenas prácticas oficiales para claves.
Alternativa para administradores con gcloud
Ejemplo para adaptar en tu propio proyecto. Primero crea o identifica el tópico y la cuenta dedicada; estos comandos no se ejecutan desde Desk.
PROJECT_ID='TU_PROYECTO'
TOPIC_ID='TU_TOPICO'
SA_EMAIL='TU_CUENTA@TU_PROYECTO.iam.gserviceaccount.com'
KEY_FILE='./desk-pubsub.json'
gcloud pubsub topics add-iam-policy-binding "$TOPIC_ID" \
--project="$PROJECT_ID" \
--member="serviceAccount:$SA_EMAIL" \
--role='roles/pubsub.publisher'
umask 077
gcloud iam service-accounts keys create "$KEY_FILE" \
--project="$PROJECT_ID" \
--iam-account="$SA_EMAIL"
Ejecuta con una identidad administradora autorizada de tu organización, respeta su política de claves y carga únicamente el archivo generado en Desk. No publiques el archivo ni concedas permisos globales para resolver un fallo. La cuenta usada por Desk solo necesita publicación sobre el tópico; la identidad administrativa que concede acceso es distinta.
Conectar el tópico en Desk
- Agregar destino → Google Cloud Pub/Sub.
- Indicar el tópico completo y seleccionar el archivo JSON local. El formulario admite hasta 16 KB.
- Elegir el formato del payload y pulsar Probar y agregar.
- Desk usa esa identidad para publicar un evento de prueba en Google. Solo guarda si la publicación se confirma; un fallo conserva el borrador.
- Crear una regla que apunte al destino y activar Webhooks.
Pantalla 5. Completar el formulario de Google Cloud Pub/Sub
Campo/control | Qué completar | Error que debes evitar |
Tipo de destino | Google Cloud Pub/Sub | Configurarlo como HTTP con la URL de la consola de Google |
Tópico de Google Pub/Sub | projects/TU_PROYECTO/topics/TU_TOPICO | Pegar solo el nombre corto, una suscripción o una URL del navegador |
Credenciales de Google · JSON de cuenta de servicio | Selecciona el archivo JSON generado para la cuenta dedicada | Subir una API key, una credencial de usuario o un archivo de federación |
Versión del payload del destino | Formato que procesará tu consumidor | Confundirlo con el envoltorio de una suscripción push de Google |
Probar y agregar | Inicia la publicación técnica con esas credenciales | Dar por hecho que solo guarda texto sin comprobar acceso |
Cancelar | Descarta el editor | Suponer que cancela una publicación de prueba que Google ya aceptó |
Orden recomendado: elige primero el tipo de destino; después completa tópico, archivo y formato. Cambiar de HTTP a Pub/Sub limpia los datos del borrador del otro transporte.
Mientras seleccionas el archivo: se lee y valida su estructura. El guardado permanece bloqueado mientras termina la lectura. Un JSON inválido o de más de 16 KB muestra un error. Seleccionar otro archivo sustituye al anterior; no concatena dos credenciales.
Cuándo se habilita el alta: nombre completo del tópico válido, JSON aceptado y tópico no duplicado entre tus destinos. Esto no sustituye la prueba de permisos: la validación final requiere que Google acepte la publicación.
Qué NO estás configurando en esta pantalla: suscripción, URL push de un consumidor, política de ACK, retención o permisos de lectura. Estas partes pertenecen a Google Cloud y a tu aplicación.
Pantalla 6. Corregir una prueba de Pub/Sub fallida
En esta imagen el archivo fue aceptado por el formulario, pero el tópico de prueba no existe. El mensaje rojo no significa necesariamente que el JSON tenga un error de sintaxis: también puede fallar la autorización o el acceso al recurso.
- Comprueba el proyecto y el nombre exacto del tópico.
- Comprueba que la cuenta de servicio exista y que la clave no esté revocada.
- Revisa Publisher sobre ese tópico concreto; no concedas Owner o Editor para “hacer que funcione”.
- Si cambiaste permisos recientemente, comprueba su aplicación en Google y vuelve a probar.
- Corrige el dato y pulsa nuevamente Probar y agregar.
Qué quedó guardado: nada del destino nuevo. El formulario conserva el borrador para reintentar y no crea una tarjeta como si la conexión hubiera funcionado. No compartas el JSON ni la clave privada para pedir ayuda: basta con el tipo de error, fecha/hora y datos del recurso que tu organización permita comunicar.
La clave se envía por HTTPS al backend para usar la integración; no se trata de un archivo adjunto público. No se devuelve por API ni se vuelve a mostrar al abrir el editor. La integración necesita conservar una credencial utilizable; “no visible” no significa que no se almacene.
Pantalla 7. Interpretar el destino Pub/Sub guardado
Indicador/control | Significado |
Pub/Sub y nombre completo del tópico | Destino al que se publicarán los mensajes |
Payload 2.0.0 en el ejemplo | Formato seleccionado; no es el estado de una suscripción |
Google IAM · Credenciales guardadas | Desk conserva una credencial para publicar; no revela el archivo |
Google IAM · Identidad provisionada, si aparece en una conexión anterior | Se conserva una identidad configurada previamente; no significa acceso anónimo |
Sin reglas de envío | Todavía falta asociar al menos una regla moderna |
Destino guardado, mensaje verde | Terminó el alta del destino |
Crear regla para este destino | Acceso al editor de reglas; no es una regla ya guardada |
Lee la combinación de estados: la prueba de publicación funcionó, el destino existe y la credencial se guardó, pero aún no hay eventos de negocio configurados en la captura. Continúa con Crear regla para este destino o Agregar regla y verifica el destino elegido antes de guardar.
La etiqueta de credenciales no es un monitor continuo. Si posteriormente revocas la clave o quitas Publisher en Google, la tarjeta puede seguir indicando que existe una credencial almacenada aunque fallen publicaciones nuevas. Verifica el acceso con una prueba/entrega y con tus registros de Google.
Que la aplicación consumidora no vea un mensaje no invalida automáticamente la publicación: revisa por separado suscripción, permisos del consumidor y confirmación de recepción.
Qué ocurre con la autenticación Google
Desk + JSON de tu cuenta de servicio
→ biblioteca Google obtiene/renueva un token de acceso
→ Google comprueba permiso de publicación en el tópico
→ Pub/Sub acepta el mensaje
→ tu suscripción lo entrega al consumidor
→ el consumidor confirma recepción a GoogleNo copies manualmente un access token temporal de Google en el campo HTTP Authorization. No hay un callback del consumidor a Desk para crear la credencial. El permiso Publisher no permite a Desk leer tu suscripción. La identidad del consumidor debe recibir los permisos de consumo que corresponden a tu infraestructura.
Publicación confirmada no equivale a consumo confirmado. Configura una suscripción antes de probar si necesitas conservar esa entrega de prueba. La retención y el comportamiento de mensajes sin suscripción dependen de tu configuración en Google Cloud; esta guía no los configura desde Desk.
Rotación y comprobación
Crea una segunda clave para la misma cuenta, abre Editar destino, carga el JSON nuevo y pulsa Probar y guardar destino. Verifica una entrega de negocio y después revoca la clave anterior en Google. Sin un archivo nuevo se conserva la clave guardada. Para usar otro tópico, crea otro destino y actualiza las reglas. No elimines la cuenta de servicio activa antes de sustituir la conexión.
Pantalla 8. Editar el formato o rotar la clave Google
Elemento de la captura | Cómo usarlo |
Tópico y tipo del destino | Se conservan; el editor no permite reemplazarlos |
Credenciales guardadas no se muestran | Es el comportamiento esperado; no necesitas recuperarlas para mantener la conexión |
Selector de archivo | Déjalo vacío para conservar la clave; selecciona un JSON nuevo para reemplazarla |
Versión del payload | Cambia el contrato de los mensajes que envíen las reglas hacia este destino |
Probar y guardar destino | Con un archivo nuevo, comprueba publicación antes de sustituir la clave guardada |
Cancelar | Abandona este borrador; no guarda el cambio de formato o credencial |
Ejemplo de la imagen: el destino ya tiene una regla y el payload elegido es 1.0.0. Se seleccionó una segunda clave para probar una rotación. Esto no convierte la integración general al sistema antiguo.
Rotación paso a paso:
- Crea la segunda clave de la misma cuenta sin revocar aún la anterior.
- Carga el archivo nuevo y espera a que termine su lectura.
- Guarda y comprueba el resultado de la prueba de publicación.
- Dispara un evento de negocio y confirma recepción con el consumidor.
- Revoca la clave anterior en Google cuando la nueva esté validada.
Si la comprobación de la clave nueva falla, no se reemplaza la credencial almacenada. No revoques primero la anterior, porque podrías interrumpir las entregas.
Cambio solo de formato: si no cargas un archivo, se conserva la credencial. No interpretes esa conservación como una rotación ni como prueba de que tus permisos IAM siguen vigentes. Confirma que tu consumidor soporta el formato nuevo antes de afectar a todas las reglas asociadas.
Eventos y acciones
Identificador | Cuándo usarlo |
CASE_CREATED | Creación de un ticket |
CASE_CLOSED | Cierre de un ticket |
CASE_IGNORED | Ticket ignorado |
CASE_ASSIGNED | Asignación de ticket |
MESSAGE | Mensaje entrante |
OUTBOUND_MESSAGE | Creación de mensaje saliente |
OUTBOUND_MESSAGE_SENT | Mensaje saliente marcado como enviado; es distinto del evento de creación |
CASE_CUSTOMDATA_SAVED | Guardado de metadatos del ticket |
USER_CUSTOMDATA_SAVED | Guardado de metadatos del cliente |
Los eventos de metadatos corresponden al guardado; no asumas que cada guardado modifica un valor ni que identifica por sí solo el origen del cambio. Usa condiciones para filtrar lo necesario. La nueva configuración no suscribe automáticamente a todos los eventos: crea explícitamente las reglas requeridas.
Pantalla 9. Elegir el evento que dispara la regla
- Pulsa Agregar regla en Reglas de envío, o entra desde el acceso posterior al alta de un destino.
- Escribe un nombre descriptivo: por ejemplo, “Enviar cierres de soporte a mi sistema”.
- Abre Evento y elige una de las opciones de la lista.
- Configura las condiciones y la acción; seleccionar el evento por sí solo no guarda nada.
Qué muestra esta captura: el desplegable está abierto para revisar los eventos disponibles. Es una selección dentro de una regla, no una pantalla para activar globalmente todos los eventos a la vez.
Diferencias que suelen confundirse: Mensaje saliente corresponde a la creación; Mensaje saliente enviado corresponde al estado de envío. Los eventos de metadatos corresponden al guardado, por lo que no deben interpretarse automáticamente como “el valor cambió”. La lista anterior relaciona los nombres funcionales con sus identificadores técnicos.
Pantalla 10. Completar condiciones, acciones y destino antes de guardar
Zona/campo de la ventana | Qué debes decidir |
Nombre de la regla | Un nombre que permita reconocer su propósito al volver a la lista |
Evento | Qué suceso dispara la evaluación; en la imagen, Caso cerrado |
Condiciones / Agregar condición | Filtros adicionales usando los campos y operadores que ofrece el editor |
Acción | Notificar a un destino para la configuración moderna |
URL del destino | Selecciona el destino guardado; en Pub/Sub el selector presenta el tópico aunque conserve esta etiqueta |
Agregar acción | Añade otra acción a la misma regla; completa también su destino |
Guardar regla | Persiste la regla completa |
Cancelar o cerrar la ventana | No guarda el borrador |
Condiciones vacías: la regla no añade un filtro adicional; puede evaluarse para los eventos de ese tipo dentro de su ámbito. Añade condiciones si necesitas limitar los envíos. Para un ejemplo inicial, utiliza un contexto de prueba que no involucre datos sensibles.
Destino de la acción: no escribas aquí un token ni un JSON. Las credenciales ya pertenecen al destino y se reutilizan por ID. Comprueba la URL o tópico completo y el formato indicado en la opción; dos integraciones distintas pueden tener nombres parecidos.
Guardar deshabilitado: revisa que el nombre no esté vacío, que las condiciones sean válidas y que cada acción moderna tenga un destino. Agregar una segunda acción incompleta no produce un “envío parcial configurado”; debes completarla antes de guardar.
Si editas un destino compartido: todas las reglas que lo referencian verán sus ajustes. Si quieres un formato o credencial distinta para otro uso, diseña esa separación explícitamente y revisa los destinos permitidos por el editor.
Pantalla 11. Confirmar que la regla quedó asociada
Después de Guardar regla, comprueba:
- La ventana se cerró y la regla aparece en la sección Reglas de envío.
- La fila muestra el evento correcto, el destino correcto y el payload esperado.
- La tarjeta del destino cambia de Sin reglas de envío a Usado en 1 regla, o al número que corresponda.
- Al recargar, la regla sigue presente.
- Webhooks está activo cuando vayas a realizar la prueba de negocio.
Esto confirma configuración, no recepción. El contador de reglas no cuenta mensajes entregados, y el color azul no acredita que el consumidor esté funcionando.
Prueba completa del ejemplo Caso cerrado: cierra un ticket de prueba autorizado, verifica que corresponda al establecimiento/ámbito de la regla y observa en tu receptor HTTP o consumidor Pub/Sub el evento esperado. Registra el ID del ticket, tipo de evento y hora para correlacionarlo; no registres el secreto. En Pub/Sub comprueba además el ACK del consumidor; en HTTP, que el receptor aceptó y persistió lo necesario antes de responder.
Los botones Editar y Quitar junto a una regla afectan a esa regla. Son distintos de Editar/Quitar en la tarjeta del destino. Eliminar una regla no elimina tu receptor ni desconecta por sí solo las demás reglas que compartan el destino.
La acción moderna Notificar a un destino selecciona un destino guardado. Una regla puede tener más de una acción. La acción legada Enviar notificación depende de la configuración general v1 existente. Crear un destino no actualiza automáticamente las acciones legadas; revisa las reglas al migrar.
Configuraciones legadas existentes
El editor legado conserva el guardado explícito. Sus credenciales se administran en la configuración general; no supongas que crear un destino moderno cambia la acción legada de tus reglas.
Pantalla 12. Mantener una configuración legada sin confundir los guardados
Elemento del editor legado | Cómo funciona |
Habilitar envíos | Forma parte del formulario general; revisa el guardado explícito |
Lista de destinos y campo para agregar URL | Son los endpoints de la configuración legada existente |
Enviar Authorization | Controla si ese flujo HTTP adjunta la credencial configurada |
Token nuevo, cuando se muestra | Permite reemplazarla; una credencial guardada no se revela |
Aviso amarillo al desactivar Authorization | Advierte el mismo riesgo HTTP explicado en las pantallas 2–4 |
Guardar configuración general | Persiste los cambios de este formulario legado |
Reglas de envío y su propio Guardar regla | Administran por separado cuándo se ejecutan las acciones |
Diferencia decisiva con la pantalla 1: en el editor legado no debes asumir que cambiar una casilla equivale al guardado inmediato del interruptor moderno. Guarda la configuración general y luego recarga para verificarla. Guardar una regla tampoco guarda automáticamente los cambios pendientes del formulario general.
Compatibilidad: que una instalación ya tenga v1 permite mantener su configuración existente. No significa que puedas crear nuevas configuraciones generales v1. Tampoco confundas esa versión general con el payload1.0.0 que puede utilizar un destino moderno.
Antes de migrar reglas: identifica cuáles usan Enviar notificación (legado) y cuáles Notificar a un destino (moderno). Crear un destino nuevo no reescribe las acciones existentes ni mueve sus credenciales. Planifica y verifica el cambio para no dejar una regla sin la configuración que necesita.
Versiones y payloads
La versión general de la integración y el formato del payload son dos configuraciones distintas. El sistema moderno v2 puede enviar un payload en formato1.0.0 a un destino que necesita compatibilidad. No crees una configuración general v1 nueva: se conserva únicamente donde ya existía.
Ejemplo ilustrativo de campos del payload1.0.0, con IDs ficticios:
{"ticket_id":"ID_TICKET_FICTICIO","cm_id":null,"event":"CASE_CLOSED","client_id":123,"v":"1.0"}Otros campos dependen del contexto del evento. En2.0.0 la estructura depende del tipo de evento: tickets, mensajes y metadatos no comparten necesariamente las mismas claves raíz. No uses un único parser rígido para los nueve eventos. En Pub/Sub, el formato de entrega a tu aplicación también depende de si usas una biblioteca pull o una suscripción push; no confundas el envoltorio de Google con el payload de Desk.
La prueba de conexión contiene un evento técnico distinto del payload de negocio:
{"ticket_id":"test_ticket","client_id":"ID_ESTABLECIMIENTO","EVENT":"test_event"}Checklist de una conexión realmente terminada
Comprobación | Evidencia que debes obtener | Qué todavía no demuestra |
Datos del formulario válidos | El botón de alta se habilita | Que el receptor o Google hayan aceptado una prueba |
Prueba de conexión correcta | Se crea el destino y aparece su tarjeta | Que exista una regla de negocio |
Regla guardada | La fila y la asociación permanecen tras recargar | Que el evento haya ocurrido o cumplido condiciones |
Webhooks activo | El interruptor conserva Activos | Que la red o el consumidor sigan disponibles |
Evento real de prueba | Payload esperado observado en tu sistema | Que tu proceso de negocio haya concluido si lo procesa después |
Procesamiento confirmado | Persistencia/resultado interno y ACK o respuesta adecuados | Entrega exactamente una vez o ausencia futura de errores |
Antes de pasar a operación:
- Comprueba el establecimiento y los destinos configurados; no reutilices las URLs de las capturas.
- Verifica que una petición HTTP sin credencial o con un secreto incorrecto sea rechazada antes de procesarse.
- Verifica que el mismo receptor acepte el secreto correcto y el evento técnico de conexión.
- Dispara un evento de negocio y comprueba su esquema real; no uses el payload de prueba como contrato de los nueve eventos.
- Revisa si hay reglas duplicadas o más de una acción que puedan generar varias notificaciones.
- Prepara cómo detectar errores, rotar secretos y recuperar el consumidor de acuerdo con tu operación.
- Después de rotar, elimina la credencial anterior solo cuando hayas verificado la nueva.
No se requiere ni se documenta un callback del receptor a Desk para “activar” el secreto. La confirmación depende del transporte: respuesta HTTP del receptor, aceptación de publicación de Google y, por separado, procesamiento/ACK del consumidor.
Verificación y problemas frecuentes
Situación | Qué revisar |
HTTP devuelve401/403 | Valor completo, prefijo Bearer si se usó, espacios y configuración del receptor |
HTTP sin Authorization | Activar autenticación y verificarla en el servidor; revisar el riesgo antes de aceptar eventos |
JSON inválido | Debe ser una clave JSON de cuenta de servicio, no una API key, credencial OAuth de usuario ni archivo de federación |
Pub/Sub no conecta | Nombre del tópico, cuenta/clave vigentes, Pub/Sub habilitado y Publisher sobre ese tópico |
Google impide crear la clave | Consultar a seguridad; no evadir la política de la organización |
Prueba Pub/Sub exitosa, aplicación sin eventos | Verificar suscripción, consumidor, permisos de consumo y ACK |
Destino guardado sin eventos | Webhooks activo, regla guardada, evento correcto, condiciones cumplidas y destino seleccionado |
Evento repetido | Procesamiento idempotente según tu operación; no asumir entrega exactamente una vez |
Funciona prueba, falla negocio | La prueba tiene otro esquema; revisar parser por evento, tamaño y procesamiento durable |
El gráfico/historial de entregas no forma parte de esta implementación. Tu receptor y Google Cloud deben aportar las evidencias de publicación, consumo y errores que necesitas para operar. Para soporte, comparte fecha/hora, tipo de evento, destino y código de error; nunca la clave JSON ni el token completo.
Conversemos
¿Otro sistema necesita enterarse cuando llega o se cierra un ticket y hoy lo avisan a mano? Conversemos sobre qué evento debe disparar la notificación y qué proceso quieres conectar.