Usar webhooks para receber notificações entre serviços

Artigo
04/08/2023

O OneDrive fornece notificações serviço a serviço por meio de webhooks. Os webhooks fornecem um pipeline de notificação simples para que o aplicativo possa ser informado das alterações na unidade de um usuário sem sondar o serviço.

Quando os itens aos quais o aplicativo tem acesso na unidade de um usuário são alterados, a URL fornecida recebe uma solicitação notificando que ocorreram alterações.

Tarefas comuns

Tarefa	Método HTTP
Criar uma nova assinatura	`POST /subscriptions`
Excluir assinatura	`DELETE /subscriptions/{id}`
Atualizar uma assinatura	`PATCH /subscriptions/{id}`

Registro

Para registrar webhooks, adicione uma nova assinatura para o item que representa o início do escopo para o qual você deseja receber as alterações.

Confira os detalhes sobre como registrar uma URL para notificações em Adicionando uma nova assinatura.

Escopo de notificações

As notificações de webhook serão enviadas para seu aplicativo apenas para as alterações que cumprirem os seguintes critérios:

Um usuário autorizou seu aplicativo a ter acesso ao conteúdo do OneDrive.
O aplicativo tem acesso ao item que gera a notificação.
A sua assinatura não expirou.

O aplicativo não receberá notificações para itens compartilhados com o usuário conectado ou para itens remotos na unidade do usuário a menos que sejam criadas assinaturas separadas nos itens originais.

Recebendo notificações

Depois que sua assinatura for criada, o OneDrive enviará solicitações POST para a URL registrada quando itens no escopo de notificação forem alterados. Várias notificações para seu serviço poderão ser reunidas em lote em uma única solicitação se vários usuários tiverem alterações no mesmo período de tempo.

Notificação de exemplo

O corpo da solicitação HTTP para a URL de notificação conterá um recurso Webhook Notification semelhante ao seguinte:

{
  "value": [
    {
      "subscriptionId": "A640DFF3-0429-44FC-AF7E-30523A476864",
      "expirationDateTime": "2017-02-22T16:00:00Z",
      "resource": "/me/drive/root",
      "clientState": "client-specific string"
    }
  ]
}

Você verá que a notificação não inclui informações sobre as alterações que a dispararam. Seu aplicativo deve usar o verbo delta para detectar alterações no estado dos itens no OneDrive e armazenar o valor de syncToken para a próxima vez que você for notificado.

Tratamento de erros

Se ocorrer um erro durante o envio de uma notificação ao seu serviço, o OneDrive seguirá a lógica de retirada exponencial. Qualquer resposta com um código de status HTTP fora do intervalo de 200 299 ou que atinja o tempo limite será tentada novamente nos próximos minutos. Se a solicitação não for bem-sucedida após 15 minutos, a notificação será interrompida.

Ainda serão aplicadas notificações futuras ao serviço, embora ele tenha o direito de remover a assinatura se um número suficiente de falhas for detectado.

Expiração

Se uma data de expiração não for fornecida no momento da criação da assinatura, será fornecida uma data automaticamente. Por padrão, as assinaturas são definidas para expirar seis meses após serem criadas.

Práticas recomendadas

Ao usar webhooks, leve em conta alguns pontos importantes:

Serviço a serviço

Não tente usar webhooks para notificar dispositivos cliente diretamente. Cada aplicativo tem uma URL de webhook única que é chamada para todos os usuários. Essa URL deve apontar para um serviço que você controla. Você pode optar por fazer com que seu serviço analise as mensagens de notificação e encaminhe notificações por push apropriadas aos aplicativos cliente conforme desejado.

Responder rapidamente

Seu aplicativo tem um tempo limitado para responder à solicitação. Coloque em filas informações sobre atualizações de notificação e, em seguida, processe essas solicitações em um thread separado. Não tente extrair alterações do serviço do OneDrive antes de responder à solicitação de webhook.

Espere notificações simultâneas

Em muitas circunstâncias, você pode receber notificações para o mesmo usuário várias vezes em sucessão rápida. Por exemplo, se um usuário for novo ou estiver carregando um lote de conteúdo para o OneDrive, você poderá receber várias notificações para o mesmo usuário antes de processar a primeira notificação. Garanta que as ações que respondem às notificações de webhook lidem corretamente com esse caso.

Compartilhar via