- Endpoint HTTPS validado, respuestas 200/202 y reintentos controlados.
- Suscripciones con clientState, tokens y renovación antes de expirar.
- Limitación por latencia: evita estados lentos o drop optimizando el backend.
Conectar sensores IoT y recibir avisos en Windows sin tener que estar preguntando cada poco al servidor es posible gracias a los webhooks. En esencia, un webhook es una llamada HTTP de vuelta que un servicio hace a tu punto de entrada cuando ocurre un evento. Si quieres alertas rápidas y fiables (por ejemplo, que un sensor de temperatura dispare un aviso en tu PC), este patrón es justo lo que necesitas.
Para encajarlo en un entorno de escritorio, lo normal es exponer un endpoint seguro en la nube o en tu red, recibir la notificación, y de ahí propagarla a Windows como notificación de sistema o integrarla en tu app. A partir de aquí veremos requisitos, respuestas HTTP, reintentos, validaciones, ciclos de vida de suscripción, ejemplos prácticos (Microsoft Graph, Bot Framework, FME + Survey123, GitHub con Apps Script y Google Analytics con Cloud Run) y cómo hilarlos para que tus sensores IoT acaben avisándote en el escritorio sin comerte la cabeza.
Qué es un webhook y requisitos del endpoint
Un webhook es una API de devolución de llamada basada en HTTP. Servicios como Microsoft Graph lo utilizan para mandarte avisos cuando algo cambia en un recurso. Para hacerlo bien, tu punto de entrada debe ser público y con HTTPS, accesible via URL y con capacidad para responder en tiempo y forma; si no, los proveedores dejarán de entregarte notificaciones.
Además de ser alcanzable, el endpoint tiene que devolver respuestas HTTP correctas y consistentes. Si tu servidor no contesta a tiempo, el servicio puede empezar a descartar notificaciones. Ojo: lo que se pierde así no se recupera, de modo que conviene vigilar latencias y escalado.
Otro aspecto clave es la autorización. Muchos servicios envían o esperan tokens de acceso con caducidad al crear o mantener la suscripción. Si el token expira y no revalidas, las notificaciones no se entregan (aunque pueden reintentarse durante un periodo limitado). Preparar la reautorización periódica es parte del diseño.
Respuestas HTTP y reintentos
Los proveedores consideran entregada una notificación cuando reciben un código 2xx. En Microsoft Graph, si el endpoint devuelve cualquier otra respuesta en menos de 10 segundos, se inician reintentos durante un máximo de 4 horas con retroceso exponencial. Esta es la guía práctica:
- 200 OK cuando puedes procesar la notificación en una ventana de unos 3 segundos.
- 202 Accepted si tardarás más: cola la notificación internamente y responde aceptándola.
- 5xx si no puedes ni procesarla ni ponerla en cola; así el servicio sabe que debe reintentar.
Las notificaciones no entregadas se vuelven a mandar con un patrón de backoff. Esto significa que pueden tardar hasta 4 horas en reponerse una vez que tu endpoint vuelva a estar operativo. Planifica colas y persistencia por si tu app necesita ordenación de eventos.
Limitación: puntos de conexión lentos o que no responden
Para proteger rendimiento y seguridad, algunos servicios etiquetan endpoints con mal comportamiento. Por ejemplo, en Microsoft Graph un punto se marca como lento si más del 10% de las respuestas supera los 10 segundos en una ventana de 10 minutos; en ese estado te envían las nuevas notificaciones con un retraso adicional.
- Estado lento: si la tasa de respuestas >10 s supera el 10% en 10 minutos, se añade un retraso de 10 segundos al envío de nuevas notificaciones. Sales de ese estado cuando vuelves por debajo del 10%.
- Estado drop: si ese porcentaje supera el 15% en 10 minutos, las nuevas notificaciones pueden eliminarse hasta 10 minutos. Se sale cuando vuelves por debajo del 15%.
Si tu endpoint no cumple con estas características de rendimiento, plantéate usar Event Hubs o Event Grid como destino intermedio para absorber picos y desacoplar el procesamiento.
Seguridad: autenticación, caducidades y firewall
Cuando creas una suscripción es frecuente que el servicio envíe un token de acceso al endpoint. Ese token sirve para verificar la validez y tiene ciclo de vida distinto al de la suscripción. Si expira, dejan de entregarse las notificaciones, pero esto no implica limitación de tu endpoint; aún así, el servicio suele reintentar durante un tiempo (por ejemplo, hasta 4 horas) tras la caducidad por si revalidas a tiempo.
Para anticiparte a caducidades, añade notificaciones de ciclo de vida a la suscripción si están disponibles. Así recibirás avisos cuando falte poco para que caduque el token o la suscripción y podrás renovarlos sin interrupciones. Al renovar la suscripción, normalmente también se actualiza el token.
En cuanto a red, puedes configurar el firewall para permitir sólo conexiones entrantes de las IP de confianza del proveedor (por ejemplo, las direcciones usadas por Microsoft Graph). Esto reduce superficie de ataque y evita notificaciones falsas.
Creación de suscripciones y validación del endpoint
El patrón de alta es similar en varias plataformas. En Microsoft Graph, la aplicación cliente realiza un POST a /subscriptions indicando el recurso que quiere vigilar y el notificationUrl al que deben llegar los avisos. Si la solicitud es válida, el servicio envía una validación a esa URL y espera tu respuesta en tiempo y forma.
Durante la validación se envía un token opaco en la petición. Tu endpoint debe responder en menos de 10 segundos con un 200 OK, Content-Type text/plain y el token de validación en el cuerpo (descodificado como texto). Si no cumples, la suscripción no se crea. Es buena práctica escapar cualquier entrada que muestres para evitar inyecciones: aunque el proveedor no envía HTML ni JavaScript, trata el token como opaco.
En la suscripción se suele requerir un clientState (valor secreto acordado entre tu app y el servicio) que te permitirá validar que las notificaciones que recibes vienen del proveedor y no de terceros. Cada suscripción tiene un identificador propio, incluso si vigilas el mismo recurso con la misma URL de notificación.
Recepción y procesamiento de notificaciones
Mientras la suscripción sea válida y haya cambios, el proveedor envía POST a tu notificationUrl con los detalles del evento. A veces te mandan colecciones de avisos en un mismo lote para optimizar entregas. En el caso de Microsoft Graph, las notificaciones incluyen, entre otros, el id de la notificación, el id de la suscripción, la fecha de expiración de la suscripción, el clientState, el tipo de cambio (creado, actualizado…), el recurso afectado y datos del recurso.
Cuando te llega una notificación, valida primero el clientState. Si no coincide con el que enviaste al crear la suscripción, no la consideres válida: puede haberse originado fuera del proveedor. Después de validar, aplica tu lógica de negocio (actualizar UI, encolar para procesos, disparar notificaciones de Windows, etc.).
Ciclo de vida: renovación, eliminación y avisos de ciclo de vida
Todas las suscripciones caducan o se eliminan. Al crearla defines una expirationDateTime. Llegada esa hora, el servicio borra la suscripción y deja de enviarte notificaciones. Mientras tanto, cada notificación que recibes suele incluir la fecha de próxima expiración, lo que te permite programar la renovación con margen.
Si ya no necesitas avisos, puedes eliminar la suscripción con su identificador; si todo va bien, el servicio devuelve un 204 sin contenido. Más interesante todavía son las notificaciones de ciclo de vida (si están disponibles): proporcionando un lifecycleNotificationUrl recibes avisos cuando el token de acceso está a punto de expirar, cuando la suscripción se aproxima a su fin o si un administrador revoca permisos a tu app.
Webhooks en canales de mensajería: esquema de Bot Framework
En canales de mensajería personalizados que integran agentes o representantes, se envían eventos y mensajes al endpoint de webhook configurado. El patrón típico usa POST contra un punto final con conversación del estilo: {webhook_url}/v3/conversations/{conversationId}/activities.
La llamada se hace con cabecera Authorization (portador obtenido de la app registrada) y la política de reintentos es directa: hasta tres intentos, con un tiempo de espera de 10 segundos por intento. Tras tres fallos, no se reintenta más. Si todo va ok, tu endpoint responde 200 y el cuerpo enviado se ignora a efectos de respuesta.
Las cargas siguen el esquema de Bot Framework: campos como type (mensaje, evento o escritura), channelId, from (con id y nombre), conversation.id, textFormat (por ejemplo markdown) y attachments (con contentType y contentUrl) cuando aplica. Este modelo permite mensajes, indicadores de escritura y eventos del sistema como join/close.
En cuanto a nombres de eventos, los valores enviados en el campo name cubren situaciones como AgentAccepted, AgentClosed, ConversationClosed, AgentStartSecondaryChannel y otras del ciclo de interacción. El listado incluye, entre muchas, PrimaryAgentEndConversation, AgentDisconnected, AgentRaiseSecondaryChannel, AgentEndSecondaryChannel, CloseConversation, SupervisorForceClosedConversation, ConsultAgentInitiated, ConsultAgentFailed, ConsultAgentAcceptSession, ConsultAgentEndSession, ConsultAgentRejectSession, ConsultAgentSessionTimedOut, ConsultAgentRemoved, TransferToAgentInitiated, TransferToAgentFailed, TransferAgentAcceptSession, TransferAgentRejectSession, TransferAgentTimedOutSession, AgentEndedConsult, AgentJoinedCustomerConversation, ConsultantAgentLeftPublicConversation, TransferToQueueInitiated, TransferToQueueFailed, CustomerDisconnected, CustomerDisconnectedWaitingForAgent, AgentAssigned, OutOfOperationHoursDueToNonWorkingHours y OutOfOperationHoursDueToHolidays.
Ejemplo de implementación: app de webhook en Cloud Run
Con Google Cloud Run puedes desplegar un servicio HTTP que escuche POST y procese notificaciones de webhook. Un ejemplo sencillo con Express parsea JSON, lee la cabecera X-Goog-Channel-Token y registra el cuerpo, devolviendo 200 si todo va bien. Tras desplegar con gcloud run deploy, obtienes la URL pública del servicio; ese será el URI al que el proveedor te envíe los avisos.
En el flujo de Google Analytics Data API (v1alpha), al crear una lista de público puedes incluir un objeto de webhookNotification con el URI y un channelToken opcional para evitar suplantaciones. El proveedor espera 200 de tu endpoint; si recibe otra cosa, devuelve error (por ejemplo, podría indicar que esperaba 200 pero recibió 404). Así sabes que debes ajustar la URL o la lógica de respuesta.
Estado y contenido de las notificaciones en Analytics
La petición POST al webhook incluye una representación JSON de una operación de larga duración y un sentTimestamp (época Unix en microsegundos). Puedes usar esa marca para detectar notificaciones repetidas. Al crear una lista de público normalmente recibes dos POST: el primero al instante, con estado CREATING; el segundo cuando finaliza, marcando ACTIVE o FAILED según corresponda.
Estos envíos incluyen campos como name (ruta del recurso), audience, audienceDisplayName, dimensiones, estado, beginCreatingTime, tokens de cuota consumidos, rowCount, porcentaje completado y el propio bloque de webhookNotification (con la URI y el channelToken). Con esta estructura puedes reaccionar en tu servidor, registrar evolución y disparar acciones en Windows en cada cambio clave.
Automatización con GitHub y Apps Script
Otro caso útil es recibir eventos de GitHub mediante un webhook y transformarlos, por ejemplo, en un correo hacia una lista de distribución. Puedes publicar una aplicación web con Google Apps Script (ejecutada como tu cuenta y accesible por cualquiera), copiar su URL pública y configurarla en GitHub en Settings > Webhooks como Payload URL con content type application/json.
Durante la configuración en GitHub puedes ver opciones como la verificación SSL; en algunos escenarios de prueba se desactiva, aunque en producción lo recomendable es mantenerla activa. Terminado el alta, GitHub manda eventos a tu URL; tu script puede formatearlos y reenviarlos a un destino (por ejemplo, a un servicio de correo), cerrando el ciclo de notificación con muy poco código.
Flujos geoespaciales con Survey123 y FME Server
En entornos GIS, un webhook lanzado desde Survey123 puede alimentar un espacio de trabajo en FME Server que procese el JSON y genere salidas (por ejemplo, Excel con varias hojas). Para ello, en FME Workbench usa un Reader Text File con la opción Leer Todo el Archivo de una Vez y un JSONFlattener para trasladar campos del JSON a atributos de FME.
Al publicar el workspace en FME Server, regístralo al menos como Job Submitter. En sus propiedades, activa la opción Send HTTP Message Body to Reader para que el cuerpo del webhook llegue directamente al Reader Text File cuando se ejecute el proceso. Así te aseguras de que el contenido viaja intacto hasta tu pipeline.
La URL del webhook se genera desde la interfaz web de FME Server (Run Workspace > Advanced). Primero se crea un token que fija la validez del webhook. En el diálogo final verás la URL; para integrarla con Survey123 puedes elegir Authorization with Query String y pegarla en los parámetros de la encuesta.
Con todo listo, cada vez que un usuario envíe una encuesta, el contenido se transferirá a FME Server, y en Jobs > Completed podrás monitorizar el resultado. Esta arquitectura encaja muy bien con sensores que publican formularios o eventos, y te permite convertirlos en informes o alertas.
Del webhook a la notificación de Windows: puente práctico
Una vez resuelto el lado servidor (validación, seguridad, reintentos), toca llevar el aviso a Windows. La idea es sencilla: tu endpoint público recibe el evento del sensor y empuja una señal a tu equipo. Puedes hacerlo con un servicio intermedio que publique en un bus y un agente ligero en Windows que suscriba y muestre la notificación.
Si manejas picos, conviene incorporar colas en tu backend (por ejemplo, cuando vengan lotes de notificaciones) y aplicar idempotencia mediante identificadores de evento y sentTimestamp. De esta forma evitarás duplicados en el escritorio si el servicio reintenta o si tu agente se reconecta.
Redactor apasionado del mundo de los bytes y la tecnología en general. Me encanta compartir mis conocimientos a través de la escritura, y eso es lo que haré en este blog, mostrarte todo lo más interesante sobre gadgets, software, hardware, tendencias tecnológicas, y más. Mi objetivo es ayudarte a navegar por el mundo digital de forma sencilla y entretenida.