Create subscription

Subscribes a listener application to receive notifications when data changes.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegated (personal Microsoft account)	Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Application	Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

HTTP request

POST /subscriptions

Response

If successful, this method returns 201 Created response code and a subscription object in the response body.

Example

Request

Here is an example of the request to send a notification when the contents of a user's drive changes.

POST /subscriptions
Content-type: application/json

{
 "changeType": "updated",
 "notificationUrl": "https://contoso.azurewebsites.net/api/webhook-receiver",
 "resource": "/me/drive/root",
 "expirationDateTime": "2018-01-01T11:23:00.000Z",
 "clientState": "client-specific string"
}

Response

If the subscription is added, then a 201 Created response is returned that includes the newly created subscription object.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "1039149811asbc",
    "resource": "/me/drive/root",
    "changeType": "updated",
    "clientState": "client-specific string",
    "notificationUrl": "https://contoso.azurewebsites.net/api/webhook-receiver",
    "expirationDateTime": "2016-01-01T11:23:00.000Z"
}

Subscription validation

Before a new subscription is created, Microsoft Graph will send a request to the URL provided in the request to create a new subscription. Your service must respond to this request by returning the validation key.

If your service fails to validate the request in this way, the subscription will fail to be created.

See handling webhook validation requests for detailed information.

Error responses

See Error Responses for more info about how errors are returned.