Recepción de notificaciones de cambios a través de webhooks

Artículo
03/26/2023

Un webhook es una API de devolución de llamada definida por el usuario basada en HTTP que puede configurar en la infraestructura para recibir notificaciones de cambios y eventos de un servicio, como Microsoft Graph. Debe configurar el webhook mediante un punto de conexión seguro HTTPS conocido y accesible.

Para recibir notificaciones de cambios a través de webhooks, debe crear una suscripción al recurso para el que desea recibir una notificación de los cambios. Aunque la suscripción es válida, Microsoft Graph envía una notificación a la aplicación cada vez que se detecta un cambio en el recurso.

El artículo le guía por el proceso de administración de la suscripción de Microsoft Graph y cómo recibir notificaciones de cambios a través de webhooks.

Crear una suscripción

Para poder recibir notificaciones de cambio de Microsoft Graph, primero debe crear una suscripción. El proceso para configurar una suscripción válida implica tanto la aplicación cliente como Microsoft Graph de la siguiente manera:

La aplicación cliente envía una solicitud de suscripción para suscribirse a los cambios en un recurso específico.
Microsoft Graph comprueba la solicitud.
- Si la solicitud es válida, Microsoft Graph envía un token de validación a la dirección URL de notificación para que la aplicación cliente valide la dirección URL de notificación.
- Si la solicitud no es válida, Microsoft Graph envía una respuesta de error con un código de error y detalles.
Cuando el cliente recibe la solicitud de validación de la dirección URL de notificación, el cliente responde con el token de validación en texto sin formato, como se explica más adelante en este artículo.
Microsoft Graph valida la respuesta del token de validación del cliente y, si el token de validación es válido, responde con un identificador de suscripción.

Solicitud de suscripción

La aplicación cliente envía una solicitud POST al punto de /subscriptions conexión. En el ejemplo siguiente se muestra una solicitud básica para suscribirse a los cambios en una carpeta de correo específica en nombre del usuario que ha iniciado sesión. Para obtener más información sobre otros recursos de Microsoft Graph que admiten notificaciones de cambios, consulte Recursos admitidos.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/notificationClient",
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",
  "resource": "/me/mailfolders('inbox')/messages",
  "expirationDateTime": "2016-03-20T11:00:00.0000000Z",
  "clientState": "SecretClientState"
}


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new Subscription
{
	ChangeType = "created,updated",
	NotificationUrl = "https://webhook.azurewebsites.net/notificationClient",
	LifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	Resource = "/me/mailfolders('inbox')/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2016-03-20T11:00:00.0000000Z"),
	ClientState = "SecretClientState",
};
var result = await graphClient.Subscriptions.PostAsync(requestBody);



import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewSubscription()
changeType := "created,updated"
requestBody.SetChangeType(&changeType) 
notificationUrl := "https://webhook.azurewebsites.net/notificationClient"
requestBody.SetNotificationUrl(&notificationUrl) 
lifecycleNotificationUrl := "https://webhook.azurewebsites.net/api/lifecycleNotifications"
requestBody.SetLifecycleNotificationUrl(&lifecycleNotificationUrl) 
resource := "/me/mailfolders('inbox')/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2016-03-20T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "SecretClientState"
requestBody.SetClientState(&clientState) 

result, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.changeType = "created,updated";
subscription.notificationUrl = "https://webhook.azurewebsites.net/notificationClient";
subscription.lifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications";
subscription.resource = "/me/mailfolders('inbox')/messages";
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2016-03-20T11:00:00Z");
subscription.clientState = "SecretClientState";

graphClient.subscriptions()
	.buildRequest()
	.post(subscription);


const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  changeType: 'created,updated',
  notificationUrl: 'https://webhook.azurewebsites.net/notificationClient',
  lifecycleNotificationUrl: 'https://webhook.azurewebsites.net/api/lifecycleNotifications',
  resource: '/me/mailfolders(\'inbox\')/messages',
  expirationDateTime: '2016-03-20T11:00:00.0000000Z',
  clientState: 'SecretClientState'
};

await client.api('/subscriptions')
	.post(subscription);


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new Subscription();
$requestBody->setChangeType('created,updated');

$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/notificationClient');

$requestBody->setLifecycleNotificationUrl('https://webhook.azurewebsites.net/api/lifecycleNotifications');

$requestBody->setResource('/me/mailfolders(\'inbox\')/messages');

$requestBody->setExpirationDateTime(new DateTime('2016-03-20T11:00:00.0000000Z'));

$requestBody->setClientState('SecretClientState');



$result = $graphServiceClient->subscriptions()->post($requestBody);


Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	changeType = "created,updated"
	notificationUrl = "https://webhook.azurewebsites.net/notificationClient"
	lifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications"
	resource = "/me/mailfolders('inbox')/messages"
	expirationDateTime = [System.DateTime]::Parse("2016-03-20T11:00:00.0000000Z")
	clientState = "SecretClientState"
}

New-MgSubscription -BodyParameter $params

Se requiere la propiedad clientState . Al establecer esta propiedad, el servicio puede confirmar que las notificaciones de cambio que recibe se originan en Microsoft Graph. Por eso, el valor de la propiedad debe permanecer secreto y ser conocido solo por la aplicación y el servicio de Microsoft Graph.

Si se ejecuta correctamente, Microsoft Graph muestra un código 201 Created y un objeto subscription en el cuerpo.

Cada suscripción tiene un identificador de suscripción único, incluso si tiene varias suscripciones que supervisan el mismo recurso y usan la misma dirección URL de notificación.

Nota:

Cualquier parámetro de cadena de consulta incluido en la propiedad notificationUrl se incluirá en la solicitud HTTP POST cuando se entreguen notificaciones al servicio.

validación de notificationUrl

Al crear una suscripción para recibir notificaciones de cambios a través de webhooks, Microsoft Graph valida primero el punto de conexión de notificación que se proporciona en la propiedad notificationUrl de la solicitud de suscripción. El proceso de validación es el siguiente:

Microsoft Graph codifica un token de validación e lo incluye en una solicitud POST a la dirección URL de notificación como se indica a continuación.
```
Content-Type: text/plain; charset=utf-8
POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
```
El cliente debe descodificar correctamente la dirección URL para obtener el token de validación de texto sin formato de Microsoft Graph.

Escapar de cualquier CÓDIGO HTML o JavaScript es una buena práctica, ya que los actores malintencionados pueden usar el punto de conexión de notificación para el tipo de ataques de scripting entre sitios. Microsoft Graph nunca envía ningún valor que contenga código HTML o JavaScript.

En general, trate el valor del token de validación como opaco, ya que el formato de token puede cambiar sin previo aviso.
El cliente debe responder con las siguientes características en un plazo de 10 segundos desde el paso 1:
- Un código de estado de HTTP 200 OK.
- Un tipo de contenido de text/plain.
- Cuerpo que incluye el token de validación de texto sin formato descodificado de dirección URL .
Importante

El token de validación debe devolverse en texto sin formato. Si el cliente devuelve un token de validación codificado, se producirá un error de validación.
Si se produce un error en la validación del punto de conexión, Microsoft Graph no crea la suscripción.

Además, puede usar la colección Microsoft Graph Postman para confirmar que el punto de conexión implementa correctamente la solicitud de validación. La solicitud de validación notificationUrl de la carpeta Misc proporciona pruebas unitarias que validan la respuesta proporcionada por el punto de conexión.

resultados de pruebas de respuesta de validación

Recibir notificaciones

Aunque la suscripción es válida y hay cambios en el recurso al que se suscribió, Microsoft Graph envía una POST solicitud a notificationUrl con detalles de los cambios. Esta carga es la notificación de cambio.

En la mayoría de las suscripciones, Microsoft Graph no retrasa el envío de notificaciones, sino que entrega todas las notificaciones dentro del Acuerdo de Nivel de Servicio a menos que el servicio experimente un incidente.

Una carga de notificación de cambio enviada a la aplicación puede contener una colección de notificaciones de cambio relacionadas con las suscripciones.

Ejemplo de notificación de cambio

Cuando el usuario recibe un correo electrónico, Microsoft Graph envía un objeto de notificación de cambio a la aplicación cliente, como se muestra en el ejemplo siguiente. Vea changeNotificationCollection y el elemento changeNotification relacionado para obtener más información sobre la carga de la notificación.

Cuando se producen muchos cambios, es posible que Microsoft Graph envíe varias notificaciones que se corresponden con distintas suscripciones en la misma POST solicitud.

{
  "value": [
    {
      "id": "lsgTZMr9KwAAA",
      "subscriptionId":"{subscription_guid}",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@{tenant_guid}/messages/{long_id_string}",
      "tenantId": "84bd8158-6d4d-4958-8b9f-9d6445542f95",
      "resourceData":
      {
        "@odata.type":"#Microsoft.Graph.Message",
        "@odata.id":"Users/{user_guid}@{tenant_guid}/Messages/{long_id_string}",
        "@odata.etag":"W/\"CQAAABYAAADkrWGo7bouTKlsgTZMr9KwAAAUWRHf\"",
        "id":"{long_id_string}"
      }
    }
  ]
}

Procesar la notificación de cambios

El servicio debe procesar cada notificación de cambio que reciba. Estas son las tareas mínimas que debe realizar la aplicación para procesar una notificación:

Después de recibir la notificación de cambio, envíe un código de clase 2xx a Microsoft Graph. Si Microsoft Graph no recibe un código de clase 2xx en 3 segundos, intenta volver a enviar la notificación de cambio varias veces, hasta 4 horas. Si Microsoft Graph sigue sin recibir un código 2xx dentro del período, descarta la notificación de cambio. Si la aplicación cliente no responde de forma coherente en 3 segundos, es posible que las notificaciones estén sujetas a limitación.

Si el servicio puede tardar más de 3 segundos en procesar la notificación de cambio, debe conservar la notificación, devolver un 202 - Accepted código de estado en la respuesta a Microsoft Graph y, a continuación, procesar las notificaciones a su capacidad. Si la notificación no se conserva, devuelva un código de clase 5xx para indicar un error para que Microsoft Graph pueda volver a intentar la notificación.

Si se espera que el servicio tarda menos de 3 segundos, debe procesar las notificaciones y devolver un 200 - OK código de estado a Microsoft Graph. Si la notificación no se procesa correctamente, devuelve un código de clase 5xx para indicar un error para que Microsoft Graph pueda reintentar la notificación.
Validar la propiedad clientState. Debe coincidir con el valor enviado originalmente con la solicitud de creación de suscripción.

Si hay un error de coincidencia, no considere la notificación de cambio como válida. Es posible que la notificación de cambio no se haya originado en Microsoft Graph y que haya sido enviada por un actor no autorizado. También debe investigar de dónde proviene la notificación y tomar las medidas adecuadas.
Actualice la aplicación cliente en función de la lógica de negocios.

Renovación de una suscripción

Hay muchas razones por las que es posible que tenga que renovar una suscripción. Para obtener más información, consulte notificaciones de ciclo de vida.

Cuando se suscribe a las notificaciones de ciclo de vida, Microsoft Graph le avisa cuando una suscripción está casi expirando y se debe renovar. Si no se suscribe a las notificaciones de ciclo de vida, puede usar subscriptionExpirationDateTime para supervisar cuándo la aplicación debe enviar una solicitud de renovación de suscripción.

Para renovar la suscripción, se requiere la propiedad expirationDateTime . Si no renueva una suscripción a tiempo, Microsoft Graph elimina la suscripción y la aplicación no recibirá notificaciones de cambios futuras para la suscripción.

Solicitud de renovación de suscripción

PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
Content-Type: application/json

{
  "expirationDateTime": "2016-03-22T11:00:00.0000000Z"
}


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new Subscription
{
	ExpirationDateTime = DateTimeOffset.Parse("2016-03-22T11:00:00.0000000Z"),
};
var result = await graphClient.Subscriptions["{subscription-id}"].PatchAsync(requestBody);



import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewSubscription()
expirationDateTime , err := time.Parse(time.RFC3339, "2016-03-22T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 

result, err := graphClient.Subscriptions().BySubscriptionId("subscription-id").Patch(context.Background(), requestBody, nil)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2016-03-22T11:00:00Z");

graphClient.subscriptions("{id}")
	.buildRequest()
	.patch(subscription);


const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  expirationDateTime: '2016-03-22T11:00:00.0000000Z'
};

await client.api('/subscriptions/{id}')
	.update(subscription);


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new Subscription();
$requestBody->setExpirationDateTime(new DateTime('2016-03-22T11:00:00.0000000Z'));



$result = $graphServiceClient->subscriptions()->bySubscriptionId('subscription-id')->patch($requestBody);


Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	expirationDateTime = [System.DateTime]::Parse("2016-03-22T11:00:00.0000000Z")
}

Update-MgSubscription -SubscriptionId $subscriptionId -BodyParameter $params

Si la solicitud de renovación de la suscripción se realiza correctamente, Microsoft Graph devuelve un 200 OK código de respuesta y un objeto de suscripción en el cuerpo de la respuesta. El objeto de suscripción incluye el nuevo valor expirationDateTime .

Eliminar una suscripción

Si la aplicación cliente ya no quiere notificaciones de cambios, puede eliminar la suscripción mediante su subscriptionId como se indica a continuación:

DELETE https://graph.microsoft.com/v1.0/subscriptions/{id}


// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

await graphClient.Subscriptions["{subscription-id}"].DeleteAsync();



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



graphClient.Subscriptions().BySubscriptionId("subscription-id").Delete(context.Background(), nil)


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

graphClient.subscriptions("{id}")
	.buildRequest()
	.delete();


const options = {
	authProvider,
};

const client = Client.init(options);

await client.api('/subscriptions/{id}')
	.delete();


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);


$graphServiceClient->subscriptions()->bySubscriptionId('subscription-id')->delete();


Import-Module Microsoft.Graph.ChangeNotifications

Remove-MgSubscription -SubscriptionId $subscriptionId

Si se ejecuta correctamente, Microsoft Graph devuelve un código 204 No Content.

Limitación

Si una dirección URL de notificación de suscripción es lenta o no responde y Microsoft Graph no recibe un código de clase 2xx en 3 segundos, Microsoft Graph intenta volver a enviar la notificación de cambio varias veces, hasta 4 horas. En este caso, Microsoft Graph podría limitar las notificaciones del punto de conexión de notificación asociado a la suscripción.

Cómo controla Microsoft Graph la limitación de notificaciones de cambio mediante webhooks

Las notificaciones se publican mediante un cliente HTTP con un tiempo de espera de 3 segundos.

Si el tiempo de publicación es superior a 2 900 ms, la respuesta se considera lenta.
A continuación, el servicio de notificación de cambios calcula el porcentaje de respuestas lentas después de que el punto de conexión reciba 100 notificaciones.
Si el porcentaje de respuestas lentas alcanza el 10 %, el punto de conexión asociado a la dirección URL de notificación se marca como un punto de conexión lento. Todas las notificaciones de todas las suscripciones asociadas al punto de conexión están sujetas a limitación.
La evaluación continúa en tiempo real y la acumulación de respuestas se vacía cada 10 minutos.

Cuando Microsoft Graph limita un punto de conexión, las notificaciones se someten a un retraso de 10 minutos y se descargan a los trabajadores dedicados a las notificaciones con errores y limitadas. Las notificaciones que no se pudieron entregar debido a una llamada HTTP incorrecta se vuelven a intentar en 10 minutos. Las notificaciones se quitan si el porcentaje de lentitud del punto de conexión limitado es mayor o igual que el 15 %.

Configuración del firewall

Puede configurar el firewall que protege la dirección URL de notificación para permitir conexiones entrantes solo desde Microsoft Graph, lo que reduce la exposición adicional a notificaciones de cambios no válidas. Para obtener una lista completa de las direcciones IP usadas por Microsoft Graph para entregar las notificaciones de cambios, consulte puntos de conexión de Office 365 adicionales.