Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Um webhook é uma API de retorno de chamada definida pelo usuário baseada em HTTP que você pode configurar em sua infraestrutura para receber notificações de alteração e eventos de um serviço, como o Microsoft Graph. Para usar webhooks, você precisa definir um ponto de extremidade protegido por HTTPS acessível publicamente que receba as notificações.
Você pode criar uma assinatura para o recurso para o qual deseja ser notificado sobre alterações. Embora a assinatura seja válida, o Microsoft Graph envia uma notificação ao seu ponto de extremidade sempre que detecta uma alteração no recurso.
O artigo orienta você pelo processo de implementação do ponto de extremidade do webhook, assinatura e gerenciamento de assinaturas do Microsoft Graph e como receber notificações de alteração por meio de webhooks.
Para obter detalhes sobre como criar notificações de alteração, consulte Notificações de alteração da API do Graph Microsoft.
Considerações sobre um ponto de extremidade de webhook
Antes de receber uma notificação por meio de webhooks, você deve criar um ponto de extremidade protegido por HTTPS acessível publicamente que seja endereçável por URL. Se o ponto de extremidade não estiver acessível publicamente, o Microsoft Graph não enviará notificações para o ponto de extremidade.
Seu ponto de extremidade deve fornecer respostas HTTP corretas, consistentes e oportunas para receber notificações de forma confiável. Se um ponto de extremidade não responder em tempo hábil, o serviço de notificação de alteração poderá começar a descartar notificações. As notificações ignoradas não podem ser recuperadas.
Seu ponto de extremidade também deve continuar autenticado no Microsoft Graph, renovando continuamente sua assinatura ou respondendo às notificações do ciclo de vida.
Códigos HTTP e lógica de repetição
Depois que o serviço de notificações de alteração do Microsoft Graph receber uma resposta HTTP 2xx do seu ponto de extremidade em 3 segundos, a notificação será considerada entregue. Se o serviço receber uma resposta HTTP não 2xx dentro dessa janela de 3 segundos ou se a solicitação expirar porque nenhuma resposta HTTP foi recebida dentro dessa janela, ele continuará a tentar novamente a entrega por até quatro horas. Para notificações que são repetidas, o tempo limite da solicitação é estendido para 10 segundos.
- Se o ponto de extremidade conseguir processar a notificação dentro da janela de 3 segundos, ele deverá retornar um
200 OKcódigo de status para o Microsoft Graph. - Caso contrário, recomendamos validar e manter a notificação em uma fila no ponto de extremidade e retornar
202 Acceptedo código de status dentro da janela de 3 segundos. - Se a notificação não for processada ou colocada na fila, retorne um código de
5xxclasse para indicar um erro para que o Microsoft Graph possa repetir a notificação.
As notificações que não forem entregues serão repetidas em intervalos de retirada exponenciais. As notificações perdidas podem levar até quatro horas para serem reenviadas depois que o ponto de extremidade ficar online.
Limitação
Por motivos de segurança e desempenho, o Microsoft Graph limita as notificações enviadas para pontos de extremidade que se tornam lentos ou não respondem. Pode incluir a eliminação de notificações de forma que não possam ser recuperadas.
Um ponto de extremidade é marcado como "lento" quando mais de 10% das respostas demoram mais do que o limite de tempo permitido de 3 segundos em uma janela de 10 minutos.
- Quando um ponto de extremidade é marcado como "lento", todas as novas notificações são enviadas após um atraso de 10 minutos.
- A cada 10 minutos, o processo tenta avaliar, com um pequeno número de notificações, se a porcentagem de tempos limite está abaixo de 10% e, em caso afirmativo, sai do estado lento.
Um ponto de extremidade é marcado como "drop" quando mais de 15% das respostas demoram mais do que a permissão de tempo limite de repetição de 10 segundos em uma janela de 10 minutos.
- Quando um ponto de extremidade é marcado como "drop", as notificações são descartadas por uma janela de 10 minutos.
- Após o término do período de 10 minutos, o processo envia periodicamente um pequeno número de notificações. O ponto de extremidade sai do estado de "queda" quando menos de 15% das respostas demoram mais do que a janela de tempo limite de 10 segundos.
Se o ponto de extremidade não puder atender a essas características de desempenho, considere usar os Hubs de Eventos ou a Grade de Eventos como destino para receber notificações.
Autenticação
Quando você cria sua assinatura, um token de acesso é enviado ao ponto de extremidade. Esse token de acesso é usado apenas para marcar a validade do seu ponto de extremidade e tem um ciclo de vida diferente da sua assinatura de notificação de alteração. Esse token de acesso geralmente expira em 1 hora.
Para garantir notificações ininterruptas, seu ponto de extremidade deve estar preparado para uma reautorização regular pelo Microsoft Graph.
Se um token de acesso expirar, as notificações não serão entregues. No entanto, ele não dispara o comportamento de limitação do ponto de extremidade e o Microsoft Graph continua a tentar enviar novamente cada notificação por até quatro horas. Portanto, se o token de acesso for atualizado dentro de 4 horas após a expiração, as notificações não enviadas serão entregues.
Recomendamos que você adicione notificações de ciclo de vida à sua assinatura para receber um aviso sobre a expiração do token para que possa autorizar novamente seu ponto de extremidade em tempo hábil.
Ao renovar a assinatura, o token de acesso também será atualizado.
Configuração do firewall
Você pode configurar o firewall que protege seu ponto de extremidade para permitir conexões de entrada somente do Microsoft Graph, reduzindo ainda mais a exposição a notificações de alteração inválidas. Para obter uma lista completa de endereços IP usados pelo Microsoft Graph para oferecer notificações de alteração, confira pontos de extremidade adicionais para Microsoft 365.
Criar uma assinatura
Importante
Várias etapas são necessárias para garantir que um canal de comunicação seguro seja estabelecido e mantido entre o serviço de notificações de alteração do Microsoft Graph e seu ponto de extremidade.
Para começar a receber notificações de alteração do Microsoft Graph, você deve criar uma assinatura usando a URL do seu ponto de extremidade (URL de notificação) para estabelecer a assinatura. O padrão de estabelecimento de uma assinatura é o seguinte:
O aplicativo cliente envia uma solicitação de assinatura para assinar alterações em um recurso específico.
O Microsoft Graph verifica a solicitação.
- Se a solicitação for válida, o Microsoft Graph enviará um token de validação para a URL de notificação do aplicativo cliente para validar a URL de notificação.
- Se a solicitação for inválida, o Microsoft Graph enviará uma resposta de erro com um código de erro e detalhes.
Quando o cliente recebe a solicitação de validação da URL de notificação, ele responde com o token de validação em texto sem formatação.
O Microsoft Graph valida a resposta do token de validação do cliente e, se o token de validação for válido, responde com uma ID de assinatura.
Solicitação de assinatura
O aplicativo cliente envia uma solicitação POST ao /subscriptions ponto de extremidade. O exemplo a seguir mostra uma solicitação básica para assinar alterações em uma pasta de email específica em nome do usuário conectado. Para obter mais informações sobre outros recursos do Microsoft Graph que dão suporte a notificações de alteração, consulte Recursos com suporte.
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"
}
A propriedade clientState é obrigatória. Definir a propriedade permite que seu serviço confirme que as notificações de alteração recebidas são originárias do Microsoft Graph. Por esse motivo, o valor da propriedade deve continuar em segredo e deve ser conhecido somente por seu aplicativo e pelo serviço do Microsoft Graph.
Se tiver êxito, o Microsoft Graph retornará um código 201 Created e um objeto subscription no corpo.
Cada assinatura tem um subscriptionId exclusivo, mesmo que você tenha várias assinaturas que monitoram o mesmo recurso e usam a mesma URL de notificação.
Observação
Qualquer parâmetro de cadeia de caracteres de consulta incluído na propriedade notificationUrl é incluído na solicitação HTTP POST quando as notificações estão sendo entregues ao seu serviço.
Assinaturas duplicadas não são permitidas. Quando uma solicitação de assinatura contém os mesmos valores para changeType e resource que uma assinatura existente, a solicitação falha com um código 409 Conflictde erro HTTP e a mensagem Subscription Id <> already exists for the requested combinationde erro .
Validação de notificationUrl
Quando você envia uma solicitação para criar uma assinatura para obter notificações de alteração por meio de webhooks, o serviço de assinatura verifica se a propriedade notificationUrl em sua solicitação de assinatura é válida. O processo de validação funciona da seguinte forma:
Observação
Se você também estiver assinando notificações de ciclo de vida , o serviço de assinatura também validará o lifecycleNotificationUrl.
Quando uma assinatura é solicitada, o Microsoft Graph codifica um token de validação e o inclui em uma solicitação POST para a URL de notificação da seguinte maneira.
Content-Type: text/plain; charset=utf-8 POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}O cliente deve decodificar corretamente a URL para obter o token de validação de texto sem formatação do Microsoft Graph.
Escapar de qualquer HTML ou JavaScript é uma boa prática porque os agentes mal-intencionados podem usar o ponto de extremidade de notificação para ataques do tipo script entre sites. O Microsoft Graph nunca envia nenhum valor contendo código HTML ou JavaScript.
Em geral, trate o valor do token de validação como opaco, pois o formato do token pode ser alterado sem aviso prévio.
O cliente deve responder com as seguintes características em até 10 segundos após a etapa 1:
- Um código de status de
HTTP 200 OK. - Um tipo de conteúdo de
text/plain. - Um corpo que inclui o token de validação de texto sem formatação decodificado por URL .
Importante
O token de validação deve ser retornado em texto sem formatação. Se o cliente retornar um token de validação codificado, a validação falhará.
- Um código de status de
Se a validação do ponto de extremidade falhar, o Microsoft Graph não criará a assinatura.
Receber notificações
Enquanto a assinatura é válida e há alterações no recurso no qual você se inscreveu, o Microsoft Graph envia uma POST solicitação para o notificationUrl com detalhes das alterações. Esta carga é a notificação de alteração.
Para a maioria das assinaturas, o Microsoft Graph não atrasa o envio de notificações, mas fornece todas as notificações dentro do SLA, a menos que o serviço esteja enfrentando um incidente.
Um conteúdo de notificação de alteração enviado ao seu ponto de extremidade pode conter uma coleção de notificações de alteração relacionadas às suas assinaturas.
Exemplo de notificação de alteração
Quando o usuário recebe um email, o Microsoft Graph envia um objeto de notificação de alteração para o aplicativo cliente, conforme mostrado no exemplo a seguir. Consulte changeNotificationCollection e o changeNotification relacionado para obter detalhes sobre o conteúdo da notificação.
Quando ocorrem muitas alterações, o Microsoft Graph pode enviar várias notificações que correspondem a diferentes assinaturas na mesma POST solicitação.
{
"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}"
}
}
]
}
Processar a notificação de alteração
Quando você recebe uma notificação de alteração:
Valide a propriedade clientState . Ela deve corresponder ao valor enviado originalmente com a solicitação de criação da assinatura.
Se houver uma incompatibilidade, não considere a notificação de alteração como válida. É possível que a notificação de alteração não seja originada do Microsoft Graph e possa ter sido enviada por um ator desonesto. Você também deve investigar de onde vem a notificação de alteração e tomar as medidas apropriadas.
Atualize seu aplicativo cliente com base em sua lógica de negócios.
Ciclo de vida da assinatura
Quando não forem mais necessárias, as assinaturas poderão ser excluídas ou expirar. Ao criar sua assinatura, você define uma data de validade usando a propriedade expirationDateTime . Depois que esse tempo passar, o Microsoft Graph excluirá a assinatura e não enviará notificações para o seu ponto de extremidade. Você também pode excluir explicitamente sua assinatura.
A maneira mais simples de continuar recebendo notificações é continuar renovando sua solicitação de assinatura. Cada notificação inclui uma propriedade subscriptionExpirationDateTime . Você pode usá-lo para orientá-lo quando renovar sua assinatura.
Cada assinatura também inclui um token de acesso concedido ao ponto de extremidade. O tempo de expiração desse token de acesso pode ocorrer antes da expiração da assinatura. Você pode gerenciar a expiração do token de acesso usando notificações de ciclo de vida para sua assinatura.
Renovar uma assinatura
PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
Content-Type: application/json
{
"expirationDateTime": "2016-03-22T11:00:00.0000000Z"
}
Se a solicitação de renovação de assinatura for bem-sucedida, o Microsoft Graph retornará um código de 200 OK resposta e um objeto de assinatura no corpo da resposta. O objeto de assinatura inclui o novo valor expirationDateTime .
Excluir uma assinatura
Se o aplicativo cliente não quiser mais notificações de alteração, ele poderá excluir a assinatura usando seu subscriptionId da seguinte maneira:
DELETE https://graph.microsoft.com/v1.0/subscriptions/{id}
Se tiver êxito, o Microsoft Graph retornará um código 204 No Content.
Notificações do ciclo de vida da sua assinatura
Para maior flexibilidade e confiabilidade ao criar uma assinatura, você também pode assinar as notificações de ciclo de vida dessa assinatura fornecendo um ponto de extremidade lifecycleNotificationUrl que recebe, processa e responde às notificações do ciclo de vida.
Quando você assina notificações do ciclo de vida, o Microsoft Graph alerta você:
- Quando o token de acesso estiver prestes a expirar.
- Quando uma assinatura está prestes a expirar.
- Quando um administrador de locatários revoga as permissões do seu aplicativo para ler um recurso.
Observação
Se um token de acesso expirar, as notificações não serão entregues ao ponto de extremidade. Mas o Microsoft Graph continua tentando enviar cada notificação novamente por até quatro horas. Portanto, se o token de acesso for atualizado dentro de 4 horas após a expiração, as notificações não enviadas serão entregues.
Para obter mais informações sobre como utilizar as notificações do ciclo de vida para sua assinatura, consulte notificações do ciclo de vida.
Resumo
Neste artigo, você aprendeu como receber notificações de alteração por meio de webhooks.
- Crie uma assinatura enviando uma solicitação POST ao
/subscriptionsponto de extremidade. - O Microsoft Graph valida o ponto de extremidade de notificação do webhook antes de concluir o processo de criação da assinatura. Um subscriptionID exclusivo está vinculado à assinatura.
- Enquanto a assinatura ainda for válida e ocorrerem alterações no recurso inscrito, o Microsoft Graph enviará notificações de alteração para o ponto de extremidade notificationUrl .
- Renove regularmente a assinatura para manter sua validade e continuar recebendo atualizações sobre as alterações assinadas.