Visão geral de webhooks do SharePoint

Artigo
04/08/2023

Os webhooks do SharePoint habilitam os desenvolvedores a criar aplicativos que fazem a assinatura para receber notificações sobre eventos específicos que ocorrem no SharePoint. Quando um evento é disparado, o SharePoint envia uma carga de HTTP POST para o assinante. Os webhooks são mais fáceis de desenvolver e consumir do que os serviços WCF (Windows Communication Foundation) usados pelos receptores de evento remoto do suplemento do SharePoint, já que os webhooks são serviços HTTP regulares (API Web).

Atualmente, os webhooks só estão habilitados para itens de lista do SharePoint. Os webhooks de item de lista do SharePoint abrangem os eventos correspondentes a alterações de item de lista para determinada lista do SharePoint ou uma biblioteca de documentos. Os webhooks do SharePoint fornecem um pipeline de notificação simples para que o aplicativo possa ser informado das alterações em uma lista do SharePoint sem sondar o serviço. Confira mais informações em Webhooks de lista do SharePoint.

Criando webhooks

Para criar um novo webhook do SharePoint, você pode adicionar uma nova assinatura para o recurso específico do SharePoint, como uma lista do SharePoint.

As seguintes informações são necessárias para criar uma nova assinatura:

Recurso. A URL do ponto de extremidade do recurso para a qual você está criando a assinatura. Por exemplo, uma URL de API de Lista do SharePoint.
URL da notificação do servidor. A URL do ponto de extremidade de serviço. O SharePoint envia um HTTP POST a esse ponto de extremidade quando ocorrerem eventos no recurso especificado.
Data de expiração. A data de expiração de sua assinatura. A data de expiração não deve ocorrer mais de 180 dias no futuro. Por padrão, as assinaturas são definidas para expirar 180 dias após serem criadas.

Se necessário, você também pode incluir as seguintes informações:

Estado do cliente. Uma cadeia de caracteres opaca passada ao cliente em todas as notificações. Você pode usar isso para validar notificações, para marcar assinaturas diferentes ou por outros motivos.

Lidando com solicitações de validação de webhook

Quando uma nova assinatura é criada, o SharePoint valida se a URL de notificação dá suporte ao recebimento de notificações de webhook. A validação é executada durante a solicitação de criação da assinatura. A assinatura só é criada se o serviço responder em tempo hábil com o token de validação.

Exemplo de solicitação de validação

Quando uma nova assinatura é criada, o SharePoint envia uma solicitação HTTP POST à URL registrada em um formato semelhante ao seguinte exemplo:

POST https://contoso.azurewebsites.net/your/webhook/service?validationtoken={randomString}
Content-Length: 0

Resposta

Para que a assinatura seja criada com êxito, o serviço deve responder à solicitação retornando o valor do parâmetro de cadeia de caracteres de consulta validationtoken como uma resposta de texto sem formatação.

HTTP/1.1 200 OK
Content-Type: text/plain

{randomString}

Se o aplicativo retornar um código de status diferente de 200 ou não responder com o valor do parâmetro validationtoken, a solicitação para criar uma nova assinatura falha.

Receber notificações

A carga de notificação informa ao aplicativo que um evento ocorreu em determinado recurso para determinada assinatura. Várias notificações para o aplicativo poderão ser reunidas em lote em uma única solicitação se ocorrerem várias alterações no recurso no mesmo período de tempo.

O corpo da carga de notificação também contém o estado do cliente se você o tiver usado ao criar a assinatura.

Recursos de notificação de webhook

O recurso de notificação define o formato dos dados fornecidos ao serviço quando uma solicitação de notificação de webhook do SharePoint é enviada à URL de notificação registrada.

Representação JSON

Cada notificação gerada pelo serviço é serializada em uma instância de webhookNotification:

{
    "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
    "clientState":"00000000-0000-0000-0000-000000000000",
    "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
    "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
    "tenantId":"00000000-0000-0000-0000-000000000000",
    "siteUrl":"/",
    "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
}

Como várias notificações podem ser enviadas ao serviço em uma única solicitação, elas são combinadas em um objeto com um único valor de matriz:

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

Propriedades

Nome da propriedade	Tipo	Descrição
recurso	Cadeia de caracteres	Identificador exclusivo da lista em que a assinatura é registrada.
subscriptionId	String	O identificador exclusivo do recurso subscription.
clientState	Cadeia de caracteres – opcional	Um valor de cadeia de caracteres opcional que é passado de volta na notificação. mensagem para esta assinatura.
expirationDateTime	DateTime	Data e hora em que a assinatura expira se não for atualizada ou renovada.
tenantId	Cadeia de caracteres	Identificador exclusivo do locatário que gerou essa notificação.
siteUrl	Cadeia de caracteres	URL relativa do servidor do site em que a assinatura é registrada.
webId	Cadeia de caracteres	Identificador exclusivo da Web em que a assinatura é registrada.

Notificação de exemplo

O corpo da solicitação HTTP para a URL de notificação de serviço contém uma notificação de webhook. O seguinte exemplo mostra uma carga com uma notificação:

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

A notificação não inclui informações sobre as alterações que a dispararam. O aplicativo deve usar a API GetChanges na lista para consultar o conjunto de alterações do log de alterações e armazenar o valor de token de alteração de chamadas subsequentes quando o aplicativo for notificado.

Tipos de eventos

Os webhooks do SharePoint só dão suporte a eventos assíncronos. Isso significa que os webhooks só são disparados depois que uma alteração aconteceu (semelhante a eventos -ed ) e, portanto, eventos síncronos (eventos de ing ) não são possíveis.

Tratamento de erros

Se ocorrer um erro ao enviar a notificação ao aplicativo, o SharePoint tenta entregar a notificação novamente até cinco vezes. Qualquer resposta com um código de status HTTP fora do intervalo de 200 299 ou que atinja o tempo limite é tentada novamente nos cinco minutos seguintes. Se a solicitação não for bem-sucedida após cinco tentativas, a notificação será interrompida. Futuras notificações ainda serão enviadas para o seu aplicativo.

Expiração

As assinaturas de webhook são definidas para expirar após 180 dias por padrão, se um valor expirationDateTime não for especificado.

Você precisa definir uma data de expiração ao criar a assinatura. A data de expiração deve ser inferior a 180 dias. O aplicativo deve lidar com a data de expiração de acordo com as respectivas necessidades, atualizando periodicamente a assinatura.

Mecanismo de repetição

Se ocorrer um evento no SharePoint e o ponto de extremidade de serviço não estiver acessível (por exemplo, devido a manutenção), o SharePoint tenta enviar a notificação. O SharePoint executa uma nova tentativa de cinco vezes com um tempo de espera de cinco minutos entre as tentativas. Se, por algum motivo, o serviço ficar inoperante por mais tempo, na próxima vez que estiver ativo e for chamado pelo SharePoint, a chamada a GetChanges() recupera as alterações que foram perdidas quando o serviço não estava disponível.

Partilhar via