到期日期。Expiration date.订阅的到期日期。The expiration date for your subscription.到期日期不应超过 180 天。The expiration date should not be more than 180 days.默认情况下，订阅被设为自创建之日起 180 天后到期。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.

处理 Webhook 验证请求Handling webhook validation requests

创建新的订阅时，SharePoint 将验证通知 URL 是否支持接收 Webhook 通知。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

创建新的订阅时，SharePoint 将以类似于以下示例的格式，将 HTTP POST 请求发送到注册的 URL：When a new subscription is created, SharePoint sends an HTTP POST request to the registered URL in a format similar to the following example:

响应Response

若要成功创建订阅，服务必须通过返回 validationToken 查询字符串参数的值以纯文本格式的响应对请求作出响应。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}

如果应用程序返回了一个状态代码而不是 200，或无法使用 validationToken 参数值做出响应，则创建新订阅的请求会失败。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.

通知并不包括任何有关触发它的更改的信息。应用程序应使用列表上的 GetChanges API，以在通知应用程序时查询更改日志中的更改集合，并存储更改令牌值用于任何后续调用。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 webhook 仅支持异步事件。这意味着在发生更改后才触发 webhook（类似于 -ed 事件），因此不可能同步（-ing 事件）。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

如果将通知发送到应用程序时出错，SharePoint 最多会重试 5 次来传递通知。If an error occurs while sending the notification to your application, SharePoint retries up to 5 times to deliver the notification.HTTP 状态代码在 200-299 范围外的任何响应或超时响应都会在 5 分钟后再次尝试。Any response with an HTTP status code outside of the 200-299 range, or that times out, is attempted again 5 minutes later.如果在 5 次尝试后请求均未成功，将会删除通知。If the request is not successful after 5 attempts, the notification is dropped.今后若有通知，仍会尝试发送到应用。Future notifications will still be attempted to your application.

到期Expiration

默认情况下，如果未指定 expirationDateTime 值，webhook 订阅将被设置为 180 天后过期。Webhook subscriptions are set to expire after 180 days by default if an expirationDateTime value is not specified.

创建订阅时需要设置到期日期。到期日期不应超过 180 天。应用程序应根据应用程序的需要，通过定期更新订阅来处理到期日期。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

如果事件发生在 SharePoint 中并且服务终结点不可访问（例如，出于维护原因），SharePoint 将重试发送通知。If an event occurs in SharePoint and your service endpoint is not reachable (for example, due to maintenance) SharePoint retries sending the notification.SharePoint 会重试 5 次，每次尝试间隔等待 5 分钟。SharePoint performs a retry of 5 times with a 5-minute wait time between the attempts.如果由于某种原因服务停用时间较长，那么下一次在它处于活动状态并通过 SharePoint 调用时，对 GetChanges() 的调用将恢复服务不可用时遗漏的更改。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.