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.

Pantalla 1 — Configuración general, destinos y reglas antes de añadir una conexión.
Pantalla 1 — Configuración general, destinos y reglas antes de añadir una conexión.
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

Advertencia de seguridad al configurar un destino HTTP sin autenticación.
Advertencia de seguridad al configurar un destino 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

  1. Implementa un endpoint HTTPS en tu infraestructura que reciba POST con JSON. No uses un receptor público de pruebas para datos reales de clientes.
  1. Genera un secreto aleatorio en un equipo seguro. Ejemplo, para ejecutar por tu equipo:
python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
  1. 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.
  1. 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.
  1. 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.
  1. Pulsa Probar y agregar. El receptor debe aceptar también el evento técnico de prueba y devolver una respuesta satisfactoria.
  1. 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 para el valor completo de Authorization. El ejemplo es ilustrativo; la credencial permanece oculta.
Campo para el valor completo de Authorization. El ejemplo es ilustrativo; la credencial permanece oculta.
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

Pantalla 4 — Indicador de riesgo en un destino HTTP sin autenticación. Configura y valida una credencial en tu receptor.
Pantalla 4 — Indicador de riesgo en un destino HTTP sin autenticación. Configura y valida una credencial en tu receptor.
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.

  1. En Google Cloud, crea una cuenta de servicio dedicada para publicación de eventos de Desk.
  1. 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.
  1. 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.
  1. Copia el nombre completo del tópico: projects/TU_PROYECTO/topics/TU_TOPICO.

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

  1. Agregar destino → Google Cloud Pub/Sub.
  1. Indicar el tópico completo y seleccionar el archivo JSON local. El formulario admite hasta 16 KB.
  1. Elegir el formato del payload y pulsar Probar y agregar.
  1. 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.
  1. Crear una regla que apunte al destino y activar Webhooks.

Pantalla 5. Completar el formulario de Google Cloud Pub/Sub

Selección de Google Cloud Pub/Sub, nombre del tópico y clave JSON de la cuenta de servicio.
Selección de Google Cloud Pub/Sub, nombre del tópico y clave JSON de la cuenta de servicio.
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

Pantalla 6 — Error de conexión con un tópico inexistente. El destino no se guarda hasta completar la comprobación.
Pantalla 6 — Error de conexión con un tópico inexistente. El destino no se guarda hasta completar la comprobación.

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.

  1. Comprueba el proyecto y el nombre exacto del tópico.
  1. Comprueba que la cuenta de servicio exista y que la clave no esté revocada.
  1. Revisa Publisher sobre ese tópico concreto; no concedas Owner o Editor para “hacer que funcione”.
  1. Si cambiaste permisos recientemente, comprueba su aplicación en Google y vuelve a probar.
  1. 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

Destino guardado con autenticación Google IAM y su estado de uso en reglas.
Destino guardado con autenticación Google IAM y su estado de uso en reglas.
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 Google

No 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

Rotación de la clave sin mostrar la credencial guardada.
Rotación de la clave sin mostrar la credencial guardada.
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:

  1. Crea la segunda clave de la misma cuenta sin revocar aún la anterior.
  1. Carga el archivo nuevo y espera a que termine su lectura.
  1. Guarda y comprueba el resultado de la prueba de publicación.
  1. Dispara un evento de negocio y confirma recepción con el consumidor.
  1. 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

Selector de eventos y configuración de una regla de envío.
Selector de eventos y configuración de una regla de envío.
  1. Pulsa Agregar regla en Reglas de envío, o entra desde el acceso posterior al alta de un destino.
  1. Escribe un nombre descriptivo: por ejemplo, “Enviar cierres de soporte a mi sistema”.
  1. Abre Evento y elige una de las opciones de la lista.
  1. 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

Pantalla 10 — Editor de una regla Caso cerrado: evento, condiciones y destino. El receptor ilustrativo no tiene Authorization; protege tu receptor con autenticación antes de enviar información.
Pantalla 10 — Editor de una regla Caso cerrado: evento, condiciones y destino. El receptor ilustrativo no tiene Authorization; protege tu receptor con autenticación antes de enviar información.
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

Pantalla 11 — Regla guardada y destino marcado Usado en 1 regla. Sustituye la URL ilustrativa por la de tu receptor y configura autenticación.
Pantalla 11 — Regla guardada y destino marcado Usado en 1 regla. Sustituye la URL ilustrativa por la de tu receptor y configura autenticación.

Después de Guardar regla, comprueba:

  1. La ventana se cerró y la regla aparece en la sección Reglas de envío.
  1. La fila muestra el evento correcto, el destino correcto y el payload esperado.
  1. La tarjeta del destino cambia de Sin reglas de envío a Usado en 1 regla, o al número que corresponda.
  1. Al recargar, la regla sigue presente.
  1. 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

Advertencia de autenticación en una configuración legada existente.
Advertencia de autenticación en una configuración legada existente.
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.

¿Esto respondió tu pregunta?
😞
😐
🤩