Overview of SharePoint webhooks

Artikel
09/26/2022

SharePoint webhooks enable developers to build applications that subscribe to receive notifications on specific events that occur in SharePoint. When an event is triggered, SharePoint sends an HTTP POST payload to the subscriber. Webhooks are easier to develop and consume than Windows Communication Foundation (WCF) services used by SharePoint Add-in remote event receivers because webhooks are regular HTTP services (web API).

Currently webhooks are only enabled for SharePoint list items. SharePoint list item webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. SharePoint webhooks provide a simple notification pipeline so that your application can be aware of changes to a SharePoint list without polling the service. For more information, see SharePoint list webhooks.

Creating webhooks

To create a new SharePoint webhook, you add a new subscription to the specific SharePoint resource, such as a SharePoint list.

The following information is required for creating a new subscription:

Resource. The resource endpoint URL you are creating the subscription for. For example, a SharePoint List API URL.
Server notification URL. Your service endpoint URL. SharePoint sends an HTTP POST to this endpoint when events occur in the specified resource.
Expiration date. The expiration date for your subscription. The expiration date should not be more than 180 days. By default, subscriptions are set to expire 180 days from when they are created.

You can also include the following information if needed:

Client State. An opaque string passed back to the client on all notifications. You can use this for validating notifications, tagging different subscriptions, or other reasons.

Handling webhook validation requests

When a new subscription is created, SharePoint validates whether the notification URL supports receiving webhook notifications. This validation is performed during the subscription creation request. The subscription is only created if your service responds in a timely manner back with the validation token.

Example validation request

When a new subscription is created, SharePoint sends an HTTP POST request to the registered URL in a format similar to the following example:

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

Response

For the subscription to be created successfully, your service must respond to the request by returning the value of the validationtoken query string parameter as a plain-text response.

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

{randomString}

If your application returns a status code other than 200, or fails to respond with the value of the validationtoken parameter, the request to create a new subscription fails.

Receiving notifications

The notification payload informs your application that an event occurred in a given resource for a given subscription. Multiple notifications to your application may be batched together into a single request if multiple changes occurred in the resource within the same time period.

The notification payload body also contains your client state if you used it when creating the subscription.

Webhook notification resource

The notification resource defines the shape of the data provided to your service when a SharePoint webhook notification request is submitted to your registered notification URL.

JSON representation

Each notification generated by the service is serialized into a webhookNotification instance:

{
    "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"
}

Because multiple notifications may be submitted to your service in a single request, these are combined together in an object with a single array value:

{
   "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"
      }
   ]
}

Properties

Property name	Type	Description
resource	String	Unique identifier of the list where the subscription is registered.
subscriptionId	String	The unique identifier for the subscription resource.
clientState	String - optional	An optional string value that is passed back in the notification. message for this subscription.
expirationDateTime	DateTime	The date and time when the subscription expires if not updated or renewed.
tenantId	String	Unique identifier for the tenant that generated this notification.
siteUrl	String	Server relative URL of the site where the subscription is registered.
webId	String	Unique identifier of the web where the subscription is registered.

Example notification

The body of the HTTP request to your service notification URL contains a webhook notification. The following example shows a payload with one notification:

{
   "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"
      }
   ]
}

The notification doesn't include any information about the changes that triggered it. Your application is expected to use the GetChanges API on the list to query the collection of changes from the change log and store the change token value for any subsequent calls when the application is notified.

Event types

SharePoint webhooks only support asynchronous events. This means that webhooks are only fired after a change happened (similar to -ed events), and thus synchronous (-ing events) are not possible.

Error handling

If an error occurs while sending the notification to your application, SharePoint retries up to 5 times to deliver the notification. Any response with an HTTP status code outside of the 200-299 range, or that times out, is attempted again 5 minutes later. If the request is not successful after 5 attempts, the notification is dropped. Future notifications will still be attempted to your application.

Expiration

Webhook subscriptions are set to expire after 180 days by default if an expirationDateTime value is not specified.

You need to set an expiration date when creating the subscription. The expiration date should be less than 180 days. Your application is expected to handle the expiration date according to your application's needs by updating the subscription periodically.

Retry mechanism

If an event occurs in SharePoint and your service endpoint is not reachable (for example, due to maintenance) SharePoint retries sending the notification. SharePoint performs a retry of 5 times with a 5-minute wait time between the attempts. If for some reason your service is down for a longer time, the next time it's up and gets called by SharePoint, the call to the GetChanges() recovers the changes that were missed when your service was not available.

Delen via