Create subscription

Important: APIs under the /beta version in Microsoft Graph are in preview and are subject to change. Use of these APIs in production applications is not supported.

Subscribes a listener application to receive notifications when data on a Microsoft Graph resource changes.

Permissions

Creating a subscription requires read permission to the resource for which the app will receive notifications. For example, to get notifications about Messages, your app needs the Mail.Read permission. The following table lists the suggested permission needed for each resource. To learn more, including how to choose permissions, see Permissions.

Resource type / Item Permission
Contacts Contacts.Read
Conversations Group.Read.All
Events Calendars.Read
Messages Mail.Read
Groups Group.Read.All
Users User.Read.All
Drive (User's OneDrive) Files.ReadWrite
Drives (SharePoint shared content and drives) Files.ReadWrite.All
Security alert SecurityEvents.ReadWrite.All

Note: The /beta endpoint allows application permissions for most resources. Conversations in a Group and OneDrive drive root items are not supported with application permissions.

HTTP request

POST /subscriptions

Request headers

Name Type Description
Authorization string Bearer {token}. Required.

Response

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

Example

Request

In the request body, supply a JSON representation of the subscription object. The clientState field is optional.

This sample request creates a subscription for notifications about new mail received by the currently signed in user.

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
   "changeType": "created,updated",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue"
}

The following are valid values for the resource property:

Resource type Examples
Mail me/mailfolders('inbox')/messages
me/messages
Contacts me/contacts
Calendars me/events
Users users
Groups groups
Conversations groups('{id}')/conversations
Drives me/drive/root
Security alert security/alerts?$filter=status eq ‘New’
Response

Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 201 Created
Content-type: application/json
Content-length: 252

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created,updated",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437"
}

Notification endpoint validation

The subscription notification endpoint (specified in the notificationUrl property) must be capable of responding to a validation request as described in Set up notifications for changes in user data. If validation fails, the request to create the subscription returns a 400 Bad Request error.