Übersicht über SharePoint-WebhooksOverview of SharePoint webhooks

SharePoint-Webhooks ermöglichen Entwicklern das Erstellen von Anwendungen, die den Empfang von Benachrichtigungen für bestimmte Ereignisse, die in SharePoint auftreten, abonnieren.SharePoint webhooks enable developers to build applications that subscribe to receive notifications on specific events that occur in SharePoint. Wenn ein Ereignis ausgelöst wird, sendet SharePoint ein HTTP POST-Payload an den Abonnenten.When an event is triggered, SharePoint sends an HTTP POST payload to the subscriber. Webhooks sind leichter zu entwickeln und zu verwenden als Windows Communication Foundation-Dienste (WCF), die von SharePoint-Add-In-Remote-Ereignisempfängern verwendet werden, da Webhooks reguläre HTTP-Dienste (Web-API) sind.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).

Webhooks sind derzeit nur für SharePoint-Listenelemente aktiviert.Currently webhooks are only enabled for SharePoint list items. Sie decken die Ereignisse ab, die bei Änderungen von Listenelementen für eine angegebe SharePoint-Liste oder eine Dokumentbibliothek ausgegeben werden. SharePoint list item webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. SharePoint-Webhooks bieten eine einfache Benachrichtigungspipeline, sodass Ihre Anwendung Änderungen an einer SharePoint-Liste erkennen kann, ohne den Dienst abzurufen.SharePoint webhooks provide a simple notification pipeline so that your application can be aware of changes to a SharePoint list without polling the service. Weitere Informationen finden Sie unter SharePoint-Listen-Webhooks.For more information, see SharePoint list webhooks.

Erstellen von WebhooksCreating webhooks

Um einen neuen SharePoint-Webhook zu erstellen, fügen Sie ein neues Abonnement zur entsprechenden SharePoint-Ressource hinzu, z. B. zu einer SharePoint-Liste.To create a new SharePoint webhook, you add a new subscription to the specific SharePoint resource, such as a SharePoint list.

Die folgenden Informationen sind für das Erstellen eines neuen Abonnements erforderlich:The following information is required for creating a new subscription:

  • Ressource. Die Ressourcenendpunkt-URL, für die Sie das Abonnement erstellen. Zum Beispiel eine SharePoint-Listen-API-URL.Resource. The resource endpoint URL you are creating the subscription for. For example, a SharePoint List API URL.
  • Server-Benachrichtigungs-URL.Server notification URL. Die URL des Dienstendpunkts.Your service endpoint URL. SharePoint sendet eine HTTP-POST an diesen Endpunkt, wenn Ereignisse in der angegebenen Ressource auftreten.SharePoint sends an HTTP POST to this endpoint when events occur in the specified resource.
  • Ablaufdatum.Expiration date. Das Ablaufdatum für Ihr Abonnement.The expiration date for your subscription. Das Ablaufdatum sollte nicht mehr als 180 Tage in der Zukunft liegen.The expiration date should not be more than 180 days. Standardmäßig wird das Ablaufdatum von Abonnements auf 180 Tage nach dem Erstellungsdatum festgelegt.By default, subscriptions are set to expire 180 days from when they are created.

Die folgenden Informationen können Sie ebenfalls einschließen:You can also include the following information if needed:

  • Clientzustand. Client State. Eine opake Zeichenfolge, die bei allen Benachrichtigungen zurück an den Client übergeben wird. An opaque string passed back to the client on all notifications. Dies können Sie zum Überprüfen von Benachrichtigungen, zum Kategorisieren unterschiedlicher Abonnements oder aus anderen Gründen verwenden.You can use this for validating notifications, tagging different subscriptions, or other reasons.

Behandeln von Webhook-ÜberprüfungsanfragenHandling webhook validation requests

Wenn ein neues Abonnement erstellt wird, überprüft SharePoint, ob die URL für die Benachrichtigung den Empfang von Webhook-Benachrichtigungen unterstützt.When a new subscription is created, SharePoint validates whether the notification URL supports receiving webhook notifications. Diese Überprüfung erfolgt während der Anforderung zum Erstellen des Abonnements.This validation is performed during the subscription creation request. Das Abonnement wird nur erstellt, wenn der Dienst in einer bestimmten Frist mit dem Überprüfungstoken antwortet.The subscription is only created if your service responds in a timely manner back with the validation token.

Beispiel für ÜberprüfungsanforderungExample validation request

Wenn ein neues Abonnement erstellt wird, sendet SharePoint eine HTTP POST-Anforderung an die eingetragene URL in einem Format ähnlich dem folgenden Beispiel: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

AntwortResponse

Damit das Abonnement erfolgreich erstellt wird, muss Ihr Dienst der Anforderung durch Zurückgeben des ValidationToken-Abfragezeichenfolgenparameters als Nur-Text-Antwort antworten.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}

Wenn Ihre Anwendung einen anderen Statuscode als 200 zurückgibt oder nicht mit dem Wert des ValidationToken-Parameters antwortet, schlägt die Anforderung zum Erstellen eines neuen Abonnements fehl.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.

Empfangen von BenachrichtigungenReceiving notifications

Die Benachrichtigungsnutzlast informiert die Anwendung darüber, dass in einer bestimmten Ressource für ein bestimmtes Abonnement ein Ereignis aufgetreten ist.The notification payload informs your application that an event occurred in a given resource for a given subscription. Mehrere Benachrichtigungen an Ihre Anwendung können in einer einzigen Anforderung zusammengefasst werden, falls in der Ressource innerhalb desselben Zeitraums mehrere Änderungen vorgenommen wurden. 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.

Die Benachrichtigungsnutzlast enthält im Textteil außerdem den Clientzustand, sofern Sie ihn beim Erstellen des Abonnements verwendet haben.The notification payload body also contains your client state if you used it when creating the subscription.

Webhook-BenachrichtigungsressourceWebhook notification resource

Die Benachrichtigungsressource definiert die Form der Daten, die Ihrem Dienst bereitgestellt werden, wenn eine SharePoint-Webhook-Benachrichtigungsanforderung an die registrierte Benachrichtigungs-URL gesendet wird.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-DarstellungJSON representation

Jede vom Dienst generierte Benachrichtigung wird in eine WebhookNotification-Instanz serialisiert: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"
}

Da in einer einzigen Anforderung mehrere Benachrichtigungen an den Dienst gesendet werden können, werden diese in einem Objekt mit einem einzigen Array-Wert zusammengefasst: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"
      }
   ]
}

EigenschaftenProperties

EigenschaftennameProperty name TypType BeschreibungDescription
resourceresource String
String Eindeutige ID der Liste, in der das Abonnement registriert ist.Unique identifier of the list where the subscription is registered.
subscriptionIdsubscriptionId StringString Der eindeutige Bezeichner für die Abonnementressource.
The unique identifier for the subscription resource.
clientStateclientState String - optional
String - optional Ein optionaler Zeichenfolgenwert, der in der BenachrichtigungsmitteilungAn optional string value that is passed back in the notification. für dieses Abonnement zurückgegeben wird.message for this subscription.
expirationDateTimeexpirationDateTime DateTimeDateTime Datum und Uhrzeit des Ablaufs des Abonnements, wenn dies nicht aktualisiert oder erneuert wird.The date and time when the subscription expires if not updated or renewed.
tenantIdtenantId String
String Eindeutige ID für den Mandanten, der diese Benachrichtigung generiert hat.Unique identifier for the tenant that generated this notification.
siteUrlsiteUrl StringString Server-relative URL der Website, auf der das Abonnement registriert wurde.Server relative URL of the site where the subscription is registered.
webIdwebId StringString Eindeutige ID des Webs, in dem das Abonnement registriert wurde.Unique identifier of the web where the subscription is registered.

BeispielbenachrichtigungExample notification

Der Hauptteil der HTTP-Anforderung an die Dienstbenachrichtigungs-URL enthält eine Webhook-Benachrichtigung.The body of the HTTP request to your service notification URL contains a webhook notification. Das folgende Beispiel zeigt eine Nutzlast mit einer Benachrichtigung: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"
      }
   ]
}

Die Benachrichtigung umfasst keine Informationen zu den Änderungen, durch die sie ausgelöst wurde. Ihre Anwendung verwendet die GetChanges-API in der Liste, um die Sammlung von Änderungen aus dem Änderungsprotokoll abzufragen und den Änderungstokenwert für alle nachfolgenden Aufrufe zu speichern, wenn die Anwendung benachrichtigt wird.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.

EreignistypenEvent types

SharePoint-Webhooks unterstützen nur asynchrone Ereignisse. Das bedeutet, dass Webhooks nur nach einer Änderung ausgelöst werden (ähnlich wie -ed-Ereignisse). Somit sind synchrone Ereignisse (-ing-Ereignisse) nicht möglich.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.

FehlerbehandlungError handling

Wenn beim Senden der Benachrichtigung an Ihre Anwendung ein Fehler auftritt, versucht SharePoint bis zu 5 Mal, die Benachrichtigung zuzustellen.If an error occurs while sending the notification to your application, SharePoint retries up to 5 times to deliver the notification. Jede Antwort, die einen HTTP-Statuscode außerhalb des Bereichs 200-299 aufweist oder die abläuft, wird in 5 Minuten erneut versucht.Any response with an HTTP status code outside of the 200-299 range, or that times out, is attempted again 5 minutes later. Wenn die Anforderung nach 5 Versuchen nicht erfolgreich ist, wird die Benachrichtigung gelöscht.If the request is not successful after 5 attempts, the notification is dropped. Weitere Benachrichtigungen an Ihre Anwendung werden weiterhin ausgeführt.Future notifications will still be attempted to your application.

AblaufExpiration

Webhook-Abonnements laufen standardmäßig nach 180 Tagen ab, wenn kein ExpirationDateTime-Wert angegeben wird.Webhook subscriptions are set to expire after 180 days by default if an expirationDateTime value is not specified.

Sie müssen beim Erstellen des Abonnements ein Ablaufdatum festlegen. Das Ablaufdatum sollte nicht länger als 180 Tage sein. Die Anwendung sollte das Ablaufdatum entsprechend den Anforderungen Ihrer Anwendung behandeln, indem das Abonnement regelmäßig aktualisiert wird.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.

WiederholungsmechanismusRetry mechanism

Wenn ein Ereignis in SharePoint auftritt und Ihr Dienstendpunkt nicht erreichbar ist (z. B. aufgrund von Wartungen), wiederholt SharePoint das Senden der Benachrichtigung.If an event occurs in SharePoint and your service endpoint is not reachable (for example, due to maintenance) SharePoint retries sending the notification. SharePoint führt 5 Wiederholungen mit 5 Minuten Wartezeit zwischen den Versuchen durch.SharePoint performs a retry of 5 times with a 5-minute wait time between the attempts. Wenn Ihr Dienst länger ausfällt, werden die in diesem Zeitraum verpassten Änderungen durch den Aufruf von GetChanges() wiederhergestellt, sobald der Dienst wieder verfügbar ist und von Sharepoint aufgerufen wird. 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.