Cómo crear webhooks fiables de Microsoft Graph para SharePoint y Microsoft 365

By Mirko Peters · 2025-11-16

Crea webhooks fiables de Microsoft Graph para SharePoint y Microsoft 365 con validación segura, renovaciones automatizadas y una entrega de notificaciones robusta.

Automatically translated with AI from the original post. Read the English original

Crear webhooks fiables de Microsoft Graph para SharePoint y Microsoft 365 puede poner a prueba incluso a desarrolladores con experiencia. Podrías encontrarte con fallos de validación si tu endpoint no devuelve el token de validación o no responde con un estado 200 OK. Entre los problemas habituales están los endpoints bloqueados por cortafuegos, las configuraciones de red incorrectas o las interferencias de middleware. Los reintentos perdidos y las suscripciones caducadas suelen aparecer cuando el servicio no recibe la solicitud de validación o cuando los endpoints no son accesibles públicamente. Aquí aprenderás a evitar estos errores y a crear un canal de notificaciones robusto y seguro, con una lista de comprobación práctica y buenas prácticas.

Puntos clave

• Los webhooks de Microsoft Graph proporcionan notificaciones en tiempo real sobre los cambios en Microsoft 365, lo que elimina la necesidad de hacer sondeos constantes.

• Asegúrate de que tu endpoint de webhook sea accesible públicamente y use HTTPS para mantener la seguridad y la fiabilidad.

• Responde rápidamente a las solicitudes de validación devolviendo el token de validación para activar correctamente tu suscripción de webhook.

• Implementa una estrategia sólida de reintentos y retroceso (backoff) para gestionar los fallos en la entrega de notificaciones y evitar la pérdida de datos.

• Automatiza las renovaciones de suscripciones y supervisa tu canal de webhooks para garantizar notificaciones continuas y fiables.

Fundamentos de los webhooks de Microsoft Graph

Qué son los webhooks de Microsoft Graph

Un webhook es una solicitud HTTP que se activa por un evento en un sistema de origen y se envía a un sistema de destino, a menudo con una carga de datos. Los webhooks son automatizados; en otras palabras, se envían automáticamente cuando se produce su evento en el sistema de origen.

Utilizas los webhooks de Microsoft Graph para recibir notificaciones en tiempo real sobre los cambios en tu entorno de Microsoft 365. Esto significa que no necesitas consultar constantemente Microsoft Graph para obtener actualizaciones. En su lugar, tu aplicación recibe una notificación en cuanto ocurre algo importante. Así te mantienes actualizado y sincronizado con los datos accesibles a través de Microsoft Graph. Además, elimina la necesidad de una infraestructura de sondeo, en la que envías solicitudes con frecuencia a Microsoft Graph para comprobar si hay cambios recientes.

Puedes configurar notificaciones para muchos tipos de eventos, como:

• Mensajes

• Eventos

• Contactos

• Usuarios

• Grupos

• Conversaciones

• Archivos de OneDrive

• Alertas

Por ejemplo, podrías querer crear automáticamente una cuenta en un sistema externo de registro de tiempo cuando un nuevo usuario se incorpore a tu organización. También podrías activar el procesamiento de contenido, como la gestión de gastos, cuando alguien añada un archivo nuevo a una biblioteca de documentos de SharePoint o a una carpeta de OneDrive.

Por qué importa la fiabilidad

Los webhooks de Microsoft Graph desempeñan un papel clave para que tus integraciones con SharePoint y Microsoft 365 respondan con rapidez y se mantengan actualizadas. Cuando tu canal de webhooks funciona de forma fiable, tus aplicaciones responden a los cambios en tiempo real. Los usuarios siempre ven los datos más recientes, lo que mejora su experiencia y reduce el riesgo de información desactualizada.

Sin embargo, los problemas de fiabilidad pueden causar daños graves:

• Los fallos en los webhooks pueden comprometer la funcionalidad de la aplicación si no se responde correctamente.

• Los picos repentinos de tráfico pueden saturar los servidores, provocando caídas del servicio y la pérdida de solicitudes de webhook.

• No procesar los webhooks puede provocar pérdida de datos e incoherencias si no existe un mecanismo de retransmisión.

• Las URL de webhook sin protección pueden ser explotadas, lo que permite a los atacantes enviar datos corruptos.

Para crear una solución robusta, debes combinar los webhooks con consultas delta para hacer un seguimiento eficiente de los cambios. También necesitas establecer procesos para comprobar y renovar las suscripciones periódicamente. En el caso de los recursos que se actualizan con frecuencia, agrupar las solicitudes ayuda a gestionar la carga.

Configuración y validación de webhooks

Configurar los webhooks de Microsoft Graph para SharePoint y Microsoft 365 implica varios pasos importantes. Debes registrar tu webhook, gestionar las solicitudes de validación y proteger tu endpoint. Cada paso desempeña un papel crítico para que tu canal de notificaciones funcione de forma fiable y segura.

Registrar los webhooks de Microsoft Graph

Empiezas creando una suscripción de webhook. Este proceso permite que tu aplicación reciba notificaciones sobre los cambios en los recursos de Microsoft 365. Sigue estos pasos para registrar tu webhook:

1. Crea un endpoint de acceso público que utilice HTTPS. Este endpoint recibirá las notificaciones de Microsoft Graph.

2. Envía una solicitud POST al endpoint /subscriptions de Microsoft Graph.

3. En la solicitud de suscripción, especifica:

   • changeType: los tipos de cambios que quieres rastrear, como "created", "updated" o "deleted".

   • notificationUrl: la URL de tu endpoint de webhook.

   • resource: el recurso que quieres supervisar, como "/users" o "/drive/root".

   • expirationDateTime: la fecha y hora en que la suscripción debe caducar.

   • Las propiedades opcionales, como clientState, te ayudan a verificar el origen de las notificaciones.

Ejemplo de solicitud de suscripción:

POST https://graph.microsoft.com/v1.0/subscriptions
Authorization: bearer eyJ0eXAiOiJ[..]
Content-Type: application/json

{
  "changeType": "updated",
  "clientState": "SecretClientState",
  "notificationUrl": "https://yourdomain.com/api/notifications",
  "resource": "/users",
  "expirationDateTime": "2024-05-01T00:00:00.0000000+00:00"
}

Debes asegurarte de que tu endpoint sea de acceso público y esté protegido con HTTPS. Microsoft Graph valida la URL de notificación antes de completar la suscripción. Además, debes renovar las suscripciones periódicamente para seguir recibiendo notificaciones. Tu endpoint debe devolver respuestas HTTP oportunas y coherentes para no perder notificaciones.

Estos son los campos necesarios para el registro:

Gestionar las solicitudes de validación

Después de registrar tu webhook, Microsoft Graph envía una solicitud de validación a tu endpoint. Debes responder correctamente para completar el proceso de suscripción. Cuando tu endpoint recibe una solicitud GET con el parámetro de consulta validationToken, debes devolver ese token en el cuerpo de la respuesta como texto sin formato y responder con un estado 200 OK.

• Si no devuelves el validationToken, se produce un error de validación. Esto significa que Microsoft Graph no puede confirmar tu endpoint y no recibirás notificaciones.

• Debes usar la propiedad clientState para verificar que las solicitudes proceden de tu suscripción.

• Devuelve siempre el validationToken en el cuerpo de la respuesta como texto sin formato en un plazo de 10 segundos.

💡 Consejo: Responder de forma rápida y precisa a las solicitudes de validación garantiza que tu suscripción de webhook se active sin problemas.

HTTPS y seguridad del endpoint

Proteger tu endpoint de webhook es esencial. Los webhooks de Microsoft Graph requieren cifrado HTTPS para proteger los datos sensibles durante la comunicación. Debes verificar las solicitudes entrantes comprobando la firma generada con una clave secreta compartida. Utiliza rutas complejas y generadas aleatoriamente en tus URL de callback para que sean más difíciles de adivinar.

• Añade una lista blanca de IP para los endpoints de la API de Microsoft Graph.

• Incluye los tokens de autenticación en los encabezados de las solicitudes.

• Supervisa el uso de tu API para detectar patrones inusuales o picos de actividad.

• Restringe el acceso a las API de Microsoft Graph y Outlook. Solo el personal autorizado debe tener acceso, y debes exigir la autenticación multifactor.

• Despliega soluciones avanzadas de seguridad de endpoints que usan análisis de comportamiento y machine learning para identificar amenazas.

• Realiza auditorías de seguridad periódicas para encontrar y corregir vulnerabilidades.

Cada callback de webhook usa un JSON Web Token (JWT) firmado en el encabezado Authentication de la solicitud HTTPS entrante. Puedes usar técnicas estándar de validación de JWT de OpenID Connect para garantizar la integridad del token.

Debes usar HTTPS para todos los endpoints de webhook. Este requisito protege tus datos y garantiza el cumplimiento de los estándares de seguridad de Microsoft. Proteger tu endpoint ayuda a prevenir el acceso no autorizado y los ataques.

Siguiendo estos pasos, configuras un flujo de Microsoft Graph Webhooks fiable y seguro para SharePoint y Microsoft 365. Así, tu aplicación recibe las notificaciones a tiempo y de forma segura.

Procesamiento y protección de las notificaciones

Una vez configurado el endpoint de webhook, debes procesar las notificaciones entrantes de forma segura y fiable. Este paso garantiza que tu aplicación solo acepte solicitudes válidas y que nunca pierdas actualizaciones importantes de Microsoft Graph Webhooks.

Autenticación y verificación de tokens JWT

Cada notificación de Microsoft Graph incluye un JSON Web Token (JWT) en el encabezado Authorization. Debes verificar este token antes de procesar cualquier payload. Una validación correcta del JWT protege tu sistema de solicitudes no autorizadas o manipuladas.

Sigue estos pasos para autenticar y verificar los tokens JWT:

1. Comprueba que el token no haya caducado. Los tokens incluyen una hora de expiración, y debes rechazar cualquier token que la haya superado.

2. Confirma que la plataforma de identidad de Microsoft emitió el token. Valida la firma del token para asegurarte de que no se ha alterado.

3. Asegúrate de que la notificación "audience" del token coincida con el ID de tu aplicación. Este paso confirma que el token estaba destinado a tu app.

4. Verifica que la propiedad azp (authorized party) coincida con el valor esperado para tu aplicación.

Consejo: Usa siempre bibliotecas de confianza para la validación de JWT. Estas bibliotecas te ayudan a evitar errores comunes y mantienen tu aplicación segura.

También debes tener en cuenta las vulnerabilidades de seguridad habituales al manejar tokens JWT:

• No verificar la firma del JWT puede permitir que los atacantes modifiquen el contenido del token sin que se detecte.

• Usar el algoritmo 'none' en el procesamiento de JWT permite a los atacantes eludir las comprobaciones de firma.

• Los secretos de firma débiles facilitan que los atacantes falsifiquen tokens válidos.

• Los atacantes pueden inyectar parámetros específicos en el encabezado JOSE para manipular la forma en que tu sistema procesa los JWT.

Siguiendo estos pasos y precauciones, garantizas que solo las notificaciones legítimas lleguen a tu aplicación.

Gestión de los payloads de notificación

Una vez autenticada la notificación, debes procesar el payload de forma segura. Los payloads de notificación contienen información sobre el evento que activó el webhook. Para mantener la integridad de los datos y evitar problemas de seguridad, debes:

• Comprobar que todos los campos obligatorios estén presentes en el payload. Los campos que faltan pueden causar errores o un procesamiento incompleto.

• Sanitiza todos los campos de texto antes de mostrarlos o almacenarlos en tu base de datos. Este paso evita ataques de inyección y la corrupción de datos.

• Usa validación de esquema para confirmar que el payload coincide con la estructura esperada. La validación de esquema te ayuda a detectar cambios inesperados o datos mal formados.

• Prepara tu código para posibles cambios de versión de la API. Un parseo flexible garantiza que tu aplicación siga funcionando aunque Microsoft actualice el formato del payload.

Nota: Validar y sanitizar los payloads protege tu sistema de datos mal formados y amenazas de seguridad.

Implementación de la lógica de reintentos y backoff

Los problemas de red o las interrupciones temporales pueden hacer que la entrega de notificaciones falle. Para evitar la pérdida de datos, necesitas una estrategia sólida de reintentos y backoff. Microsoft recomienda usar backoff exponencial y colas estructuradas para gestionar los reintentos.

Esta es una tabla que resume los mecanismos habituales de reintento y backoff:

Si no implementas una lógica adecuada de reintentos y de backoff, tu aplicación corre el riesgo de perder notificaciones o de generar inconsistencias en los datos. Las solicitudes fallidas o la limitación de velocidad (rate limiting) pueden impedirte recibir actualizaciones críticas. El backoff exponencial te ayuda a gestionar las solicitudes limitadas y reduce la probabilidad de saturar tu sistema o Microsoft Graph Webhooks.

🛡️ Práctica recomendada: Registra siempre los intentos de reintento y mueve los mensajes fallidos a una cola de abandono tras varios reintentos. Este enfoque te permite investigar y resolver los problemas persistentes sin perder datos.

Al autenticar los tokens JWT, validar los payloads e implementar una lógica de reintento fiable, creas un canal de notificaciones seguro y resiliente. Estos pasos te permiten procesar cada notificación de Microsoft Graph Webhooks de forma segura y eficiente.

Gestión de suscripciones y seguimiento de cambios

Automatización de la renovación de suscripciones

Necesitas mantener activas tus suscripciones de webhook para no perder notificaciones. Las suscripciones de Microsoft Graph caducan tras un periodo determinado. Si no las renuevas, tu aplicación dejará de recibir actualizaciones. Puedes automatizar la renovación con varios métodos:

• Envía solicitudes HTTP PATCH para actualizar la fecha de caducidad de cada suscripción.

• Programa estas solicitudes PATCH para que se ejecuten a diario. Así tus suscripciones se mantienen vigentes y evitas caducidades inesperadas.

• Registra la marca de tiempo de caducidad de cada suscripción. Renueva cualquier suscripción que esté próxima a caducar.

• Si una suscripción caduca, crea una nueva de inmediato para restablecer el flujo de notificaciones.

Consejo: Automatizar las renovaciones reduce el trabajo manual y garantiza que tu sistema siga conectado a Microsoft Graph.

Supervisión y alertas

Debes supervisar el estado de tu canal de webhooks. Configura alertas que te avisen si una suscripción no se renueva o si tu endpoint deja de responder. Usa el registro (logging) para seguir las notificaciones entrantes y los intentos de renovación. Así detectarás los problemas antes de que afecten a los usuarios.

• Supervisa el estado y las fechas de caducidad de las suscripciones.

• Configura alertas para renovaciones fallidas o notificaciones perdidas.

• Registra todos los eventos de webhook y los errores para facilitar la resolución de problemas.

🛎️ La supervisión proactiva te ayuda a resolver los problemas con rapidez y mantiene tu integración fiable.

Uso de consultas delta para el seguimiento de cambios

Las consultas delta te ayudan a seguir los cambios en los recursos de SharePoint y de Microsoft 365 de forma eficiente. Puedes usarlas para recibir solo los datos nuevos o actualizados, lo que reduce la necesidad de sondeos frecuentes y disminuye el riesgo de limitación de velocidad (throttling).

• Las consultas delta permiten que tu aplicación siga los cambios sin descargar todos los datos cada vez.

• Funcionan bien con SharePoint y Microsoft 365, y solo envían notificaciones cuando algo cambia.

• Al usar consultas delta ahorras ancho de banda y mejoras el rendimiento.

Sin embargo, las consultas delta tienen algunas limitaciones:

Nota: Prueba siempre tu implementación de consultas delta para gestionar estas limitaciones y garantizar un seguimiento preciso de los cambios.

Al automatizar las renovaciones, supervisar tu canal y usar consultas delta, creas un sistema de webhooks fiable y eficiente para SharePoint y Microsoft 365.

Puedes crear webhooks de Microsoft Graph fiables siguiendo un proceso claro. Empieza por crear suscripciones y usar consultas delta para hacer seguimiento de los cambios. Automatiza las renovaciones y supervisa tu flujo para detectar problemas. Prioriza la validación, la seguridad y la resiliencia en cada paso. Para comprobar que estás listo para producción, revisa esta lista de comprobación:

• Mantén la documentación actualizada e informa a los equipos de soporte.

• Programa comprobaciones periódicas del estado de las suscripciones.

• Usa análisis de seguridad en el pipeline de CI y mantén registros de auditoría.

Aplica estas buenas prácticas para que tus integraciones con SharePoint y Microsoft 365 sigan siendo fiables.

Preguntas frecuentes

¿Cómo se renueva una suscripción de webhook de Microsoft Graph que ha caducado?

Envía una solicitud PATCH al endpoint /subscriptions/{id} de Microsoft Graph. Actualiza el campo expirationDateTime. Programa este proceso para que se ejecute a diario. Así mantienes activas las suscripciones y evitas perder notificaciones.

¿Qué debes hacer si tu endpoint de webhook no supera la validación?

Comprueba que el endpoint devuelve el validationToken como texto plano en el cuerpo de la respuesta. Responde con el estado 200 OK. Asegúrate de que el endpoint es accesible públicamente y usa HTTPS.

¿Cómo puedes proteger tu endpoint de webhook?

Usa HTTPS en todos los endpoints. Valida los tokens JWT en cada solicitud. Restringe el acceso con autenticación y listas blancas de IP. Supervisa la actividad inusual. Revisa periódicamente tu configuración de seguridad.

¿Por qué necesitas usar consultas delta con webhooks?

Las consultas delta te permiten hacer seguimiento solo de los datos nuevos o modificados. Esto reduce el consumo de ancho de banda y mejora el rendimiento. Evitas descargar todos los datos cada vez, lo que hace tu integración más rápida y eficiente.

¿Cuál es la mejor forma de gestionar las notificaciones de webhook fallidas?

Implementa una lógica de reintentos con retroceso exponencial. Registra los intentos de reintento mediante encabezados o colas. Mueve a una cola de mensajes abandonados los mensajes que fallen tras varios reintentos. Investiga estos fallos para evitar la pérdida de datos.