Event Notifications (BETA)

Overview

Event Notifications allow you to create subscriptions to Studio resources and receive notifications of changes at a callback URI that you designate.

What Can Be Subscribed To?

Studio Resource	Events
Studio Projects	Update Rename Delete
Studio Project Items (Files and Folders)	Create Update Move Rename File Check In Delete
Studio Sessions	Update Rename Update Expiration Date Finalize Delete
Studio Session Documents	Create Delete

Important Details

Only Apps can create subscriptions; users cannot create a subscription on their own.
Each subscription can only be created in a given Studio Prime space. Subscriptions cannot span multiple Studio Prime spaces.
Subscriptions can only be created for a specific Studio Project or Studio Session; you cannot subscribe to all Projects or Sessions within a Studio Prime space.
Subscriptions require the user to have at least read permissions to the resource.

Event Notification Endpoints

Subscription Endpoint

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions

Description	Supported Requests
Use to create or list subscriptions to a Studio Session, Studio Project, Studio Project Items or Studio Session Documents.	POST, GET

Comprehensive Subscription Endpoint

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions/comprehensive

Description	Supported Requests
Use to create comprehensive subscriptions that include updates to both the parent resource, and any items within them. ex: a comprehensive subscription to a Studio Project will receive notifications about changes to both the Studio Project, and any Folders/Files (Project Items) within that Project.	POST, GET

Specific Subscription Endpoint

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions/{subscription_id}

Description	Supported Requests
Use to list or delete a specific subscription.	GET, DELETE

Parameters

Parameter Name	Description
ParentResourceType	String that specifies the Parent Object for the Subscription. Possible values: Project, ProjectItems, Sessions, SessionDocuments. These are described in the ParentResourceType table below.
Uri	Your callback URI where you will receive the notification.

ParentResourceType	Description
Projects	Use if you want to subscribe to changes made to a Studio Project. Identify the Project by its 9-digit ProjectId in the Additional Parameters table below.
ProjectItems	Use if you want to subscribe to changes made to a folder or file within a Studio Project. Identify the folder or file with its ProjectItemId in the Additional Parameters table below.
Sessions	Use if you want to subscribe to changes made to a Studio Session. Identify the Session by its 9-digit SessionId in the Additional Parameters table below.
SessionDocuments	Use if you want to subscribe to changes made to a document within a Studio Session. Identify the document by its SessionDocumentId in the Additional Parameters table below.

Additional Parameters	Description
ProjectId	Use to define the specific Studio Project that you want to subscribe to; only include when subscribing to Projects. Find a Project’s ID by making a GET request to the Projects endpoint.
ItemType	Use to define the kind of item within the Studio Project that you want to subscribe to; only include when subscribing to ProjectItems. Possible values: folder, file.
ProjectItemId	Use to define the Project Folder or File that you want to subscribe to; include when subscribing to ProjectItems. Find a Project Folder’s ID by making a GET request to the Project Folders endpoint. Find a Project File’s ID by making a GET request to the Project Files endpoint.
SessionId	Use to define the specific Session that you want to subscribe to; only include when subscribing to Sessions or SessionDocuments. Find a Session’s ID by making a GET request to the Studio Sessions endpoint.
SessionDocumentId	Use to define the document within a Session that you want to subscribe to; only include when subscribing to SessionDocuments. Find a Session Document’s ID by making a GET request to the Session Files endpoint.

Creating Subscriptions

Below are examples of how to use Event Notifications.

Changes that will trigger notifications:

Project is renamed
Project is deleted

Endpoint

Make a POST request to the subscriptions endpoint.

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions

Request Parameters

Name	Description
ParentResourceType	Specify the parent object type for the subscription, in this case, use Projects.
ProjectId	9-digit ID for the Studio Project. Find a Project’s ID by making a GET request to the Projects endpoint.
Uri	Specify where you want your notifications to go; your URI for the callback.

Example cURL Request

curl https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions \
-H "Authorization:Bearer{A Valid access_token}" \
-H "Content-Type:application/x-www-form-urlencoded" \
-d 'ParentResourceType=Projects&ProjectId=123-456-789&Uri=http://YourCallbackURI.com' \
-X POST

Example Response

{  
   "$id":"1",
   "EndpointId":521,
   "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/",
   "Source":"Studio",
   "Status":"Active",
   "SubscriptionId":1234,
   "Uri":"{Your Callback URI}",
   "Key":"432C401BFDEB6B21A986C258F8380E3F1E93FFD3"
}

Example Notification Callback

When the Studio Project Item is moved, renamed or deleted, you will get a callback. In this example, the Project File was renamed, so the EventType is “Update”. If the Project was deleted, the EventType would be “Delete”.

{  
   "Id":"{subscription GUID}",
   "SubscriptionId":1234,
   "Source":0,
   "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/",
   "Timestamp":"2018-01-23T21:45:49.6785342+00:00",
   "ExtraInformation":{  
      "ResourceType":"Projects",
      "User":"{studio user email address}",
      "EventType":"Update",
      "IdPath":null,
      "Path":null,
      "ItemType":null,
      "Name":"{Studio Project Name}"
   }
}

Changes that will trigger notifications:

Folder or File is moved
Folder or File is renamed
Folder or File is deleted

Endpoint

Make a POST request to the subscriptions endpoint.

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions

Request Parameters

Name	Description
ParentResourceType	Specify the parent object type for the subscription, in this case, use Projects.
ProjectId	9-digit ID for the Studio Project. Find a Project’s ID by making a GET request to the Projects endpoint.
ItemType	The type of Studio Project Item. Possible values: folder, file.
ProjectItemId	The ID for the Studio Project Folder or File. Find a Project Folder’s ID by making a GET request to the Project Folder endpoint. Find a Project File’s ID by making a GET request to the Project Files endpoint.
Uri	Specify where you want your notifications to go; your URI for the callback.

Example cURL Request

curl https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions \
-H "Authorization:Bearer{A Valid access_token}" \
-H "Content-Type:application/x-www-form-urlencoded" \
-d 'ParentResourceType=ProjectItems&ProjectId=123-456-789&ItemType=File&ProjectItemId=123456&Uri=http://YourCallbackURI.com' \
-X POST

Example Response

{  
   "$id":"1",
   "EndpointId":521,
   "Resource":"/Primes/{Prime ID}/Projects/{Project ID}/ProjectItems/{File ID}/",
   "Source":"Studio",
   "Status":"Active",
   "SubscriptionId":2345,
   "Uri":"{Your Callback URI}",
   "Key":"A120F4FEDBE8E217C670DA08AC4F5113C4E46DDB"
}

Example Notification Callback

{  
   "Id":"f2149d02-8c28-4b99-98d4-16a368372ee4",
   "SubscriptionId":2345,
   "Source":0,
   "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/ProjectItems/{File ID}/",
   "Timestamp":"2018-01-26T18:46:03.7836117+00:00",
   "ExtraInformation":{  
      "ResourceType":"ProjectItems",
      "User":"{User Email Address}",
      "EventType":"Update",
      "IdPath":"/{Root Folder ID}/{Folder ID}/{File ID}",
      "Path":"/{Folder Name}/{File Name}",
      "ItemType":"File",
      "Name":"{File Name}"
   }
}

Changes that will trigger notifications:

Session is renamed
Session expiration date is updated
Session status changes to Finalizing
Session is deleted

Endpoint

Make a POST request to the subscriptions endpoint.

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions

Request Parameters

Name	Description
ParentResourceType	Specify the parent object type for the subscription, in this case, use Sessions.
SessionId	9-digit ID for the Studio Session. Find a Session’s ID by making a GET request to the Sessions endpoint.
Uri	Specify where you want your notifications to go; your URI for the callback.

Example cURL Request

curl https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions \
-H "Authorization:Bearer{A Valid access_token}" \
-H "Content-Type:application/x-www-form-urlencoded" \
-d 'ParentResourceType=Sessions&SessionId=123-456-789&Uri=http://YourCallbackURI.com' \
-X POST

Example Response

{  
   "$id":"1",
   "EndpointId":523,
   "Resource":"/Primes/{Studio Prime ID}/Sessions/{SessionId}/",
   "Source":"Studio",
   "Status":"Active",
   "SubscriptionId":3456,
   "Uri":"{Your Callback URI}",
   "Key":"51C5F4A0979BEEDD63AC8264314297739DB52209"
}

Example Notification Callback

{  
   "Id":"ea3823e2-5825-4d01-b34e-ed4724ab240c",
   "SubscriptionId":3456,
   "Source":0,
   "Resource":"/Primes/{Studio Prime ID}/Sessions/{SessionId}/",
   "Timestamp":"2018-01-29T20:51:35.9509673+00:00",
   "ExtraInformation":{  
      "ResourceType":"Sessions",
      "User":"{User Email Address}",
      "EventType":"Delete",
      "IdPath":null,
      "Path":null,
      "ItemType":null,
      "Name":"{Studio Session Name}"
   }
}

This subscription will send a notification when the document is deleted.

If you want to know when documents are added to a Session, create a comprehensive subscription to the Session.

Endpoint

Make a POST request to the subscriptions endpoint.

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions

Request Parameters

Name	Description
ParentResourceType	Specify the parent object type for the subscription, in this case, use Sessions.
SessionId	9-digit ID for the Studio Session. Find a Session’s ID by making a GET request to the Sessions endpoint.
SessionDocumentId	The ID for the Studio Session Document. Find a Session Document’s ID by looking at the Id of a file returned from a GET SessionFiles request.
Uri	Specify where you want your notifications to go; your URI for the callback.

Example cURL Request

curl https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions \
-H "Authorization:Bearer{A Valid access_token}" \
-H "Content-Type:application/x-www-form-urlencoded" \
-d 'ParentResourceType=Sessions&SessionId=123-456-789&SessionDocumentId=1234567Uri=http://YourCallbackURI.com' \
-X POST

Example Response

{  
   "$id":"1",
   "EndpointId":522,
   "Resource":"/Primes/{Studio Prime ID}/Sessions/{SessionId}/SessionDocuments/{SessionDocumentId}/",
   "Source":"Studio",
   "Status":"Active",
   "SubscriptionId":4567,
   "Uri":"{Your Callback URI}",
   "Key":"757F13CEFCA517BAF13E4FA9BA6A05FFD979B0B6"
}

Example Notification Callback

{  
   "Id":"cecfaf8e-7d0f-4fb1-8547-04c07de14406",
   "SubscriptionId":4567,
   "Source":0,
   "Resource":"/Primes/{Studio Prime ID}/Sessions/{SessionId}/SessionDocuments/{SessionDocumentId}/",
   "Timestamp":"2018-01-29T21:21:48.6498765+00:00",
   "ExtraInformation":{  
      "ResourceType":"SessionDocuments",
      "User":"{User Email Address}",
      "EventType":"Delete",
      "IdPath":null,
      "Path":null,
      "ItemType":null,
      "Name":"{Session Document Name}"
   }
}

Creating a Comprehensive Subscription

A comprehensive subscription will send notifications of change to both the Parent Resource and any items within it.

For example:

A comprehensive subscription to a Studio Project will send notifications about changes to the Project, and any Folders or Files within it.
A comprehensive subscription to a Studio Session will send notifications of changes to the Studio Session and any Session Documents within it.

See What Can Be Subscribed To? for a list of changes that will trigger a notification.

To create a comprehensive subscription, make a POST request to the comprehensive subscription endpoint. In this example, we will create a comprehensive subscription to a Studio Project.

Endpoint

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions/comprehensive

Request Parameters

Name	Description
ParentResourceType	Specify the parent object type for the subscription, in this case, use Projects.
ProjectId	9-digit ID for the Studio Project. Find a Project’s ID by making a GET request to the Projects endpoint.
Uri	Specify where you want your notifications to go; your URI for the callback.

Example cURL Request

curl https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions/comprehensive \
-H "Authorization:Bearer{A Valid access_token}" \
-H "Content-Type:application/x-www-form-urlencoded" \
-d 'ParentResourceType=Projects&ProjectId=123-456-789&Uri=http://YourCallbackURI.com' \
-X POST

Example Response

{  
   "$id":"1",
   "EndpointId":522,
   "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/",
   "Source":"Studio",
   "Status":"Active",
   "SubscriptionId":5678,
   "Uri":"{Your Callback URL}",
   "Key":"432C401BFDEB6B21A986C258F8380E3F1E93FFD3"
}

Example Notification Callbacks

In the example below, the EventType is “Update” because the Studio Project was renamed.

{  
   "Id":"0531db33-9451-49fc-8436-25b9e62e844d",
   "SubscriptionId":5678,
   "Source":0,
   "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/",
   "Timestamp":"2018-01-23T21:45:49.6785342+00:00",
   "ExtraInformation":{  
      "ResourceType":"Projects",
      "User":"{User Email Address}",
      "EventType":"Update",
      "IdPath":null,
      "Path":null,
      "ItemType":null,
      "Name":"{Studio Project Name}"
   }
}

In the example below, the ItemType is “File” and the EventType is “Update”, which means that the Studio Project File was either moved or renamed.

{  
   "Id":"f2149d02-8c28-4b99-98d4-16a368372ee4",
   "SubscriptionId":5678,
   "Source":0,
   "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/ProjectItems/{File ID}/",
   "Timestamp":"2018-01-26T18:46:03.7836117+00:00",
   "ExtraInformation":{  
      "ResourceType":"ProjectItems",
      "User":"{User Email Address}",
      "EventType":"Update",
      "IdPath":"/{Root Folder ID}/{Folder ID}/{File ID}",
      "Path":"/{Folder Name}/{File Name}",
      "ItemType":"File",
      "Name":"{File Name}"
   }
}

Listing Subscriptions

List All Subscriptions

To get a list of all of a user’s subscriptions within a Studio Prime space, make a GET request to the subscriptions endpoint.

Endpoint

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions

Example cURL Request

cURL https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions \
-H "Authorization:Bearer {A Valid access_token}" \
-X GET

Example Response

{  
   "$id":"1",
   "Subscriptions":[  
      {  
         "$id":"1",
         "EndpointId":521,
         "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/",
         "Source":"Studio",
         "Status":"Active",
         "SubscriptionId":1234,
         "Uri":"{Your Callback URI}"
      },
      {  
         "$id":"3",
         "EndpointId":521,
         "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/{File ID}/",
         "Source":"Studio",
         "Status":"Active",
         "SubscriptionId":2345,
         "Uri":"{Your Callback URI}"
      },
      {  
         "$id":"4",
         "EndpointId":523,
         "Resource":"/Primes/{Studio Prime ID}/Projects/{SessionId}/",
         "Source":"Studio",
         "Status":"Active",
         "SubscriptionId":3456,
         "Uri":"{Your Callback URI}"
      },
      {  
         "$id":"5",
         "EndpointId":522,
         "Resource":"/Primes/{Studio Prime ID}/Sessions/{SessionId}/SessionDocuments/{SessionDocumentId}/",
         "Source":"Studio",
         "Status":"Active",
         "SubscriptionId":4567,
         "Uri":"{Your Callback URI}"
      },
      {  
         "$id":"6",
         "EndpointId":522,
         "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/",
         "Source":"Studio",
         "Status":"Active",
         "SubscriptionId":5678,
         "Uri":"{Your Callback URI}"
      }
   ],
   "TotalCount":6
}

List a Specific Subscription

To get a specific subscription, make a GET request to the subscription endpoint, and include the ID of the subscription that was returned when the subscription was created.

Endpoint

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions/{subscription_id}

Example cURL Request

cURL https://studioapi.bluebeam.com/PublicApi/v1/notifications/subscriptions/6789 \
-H "Authorization:Bearer {A Valid access_token}" \
-X GET

Example Response

{  
   "$id":"1",
   "EndpointId":523,
   "Resource":"/Primes/{Studio Prime ID}/Projects/{ProjectId}/",
   "Source":"Studio",
   "Status":"Active",
   "SubscriptionId":6789,
   "Uri":"{Your Callback URI}"
}

Unsubscribing

Delete a Subscription

To unsubscribe, make a DELETE request to the subscription endpoint, specifying the subscription you want to remove. When successful, you’ll get a 204 Response.

Endpoint

https://studioapi.bluebeam.com/PublicAPI/v1/notifications/subscriptions/{subscription_id}

Example cURL Request

cURL https://studioapi.bluebeam.com/PublicApi/v1/notifications/subscriptions/6789 \
-H "Authorization:Bearer {A Valid access_token}" \
-X DELETE

Overview

What Can Be Subscribed To?

Important Details

Event Notification Endpoints

Subscription Endpoint

Comprehensive Subscription Endpoint

Specific Subscription Endpoint

Parameters

Creating Subscriptions

Subscribe to a Studio Project

Changes that will trigger notifications:

Endpoint

Request Parameters

Example cURL Request

Example Response

Example Notification Callback

Subscribe to a File or Folder Within a Studio Project

Changes that will trigger notifications:

Endpoint

Request Parameters

Example cURL Request

Example Response

Example Notification Callback

Subscribe to a Studio Session

Changes that will trigger notifications:

Endpoint

Request Parameters

Example cURL Request

Example Response

Example Notification Callback

Subscribe to a Document Within a Studio Session

Endpoint

Request Parameters

Example cURL Request

Example Response

Example Notification Callback

Creating a Comprehensive Subscription

For example:

Endpoint

Request Parameters

Example cURL Request

Example Response

Example Notification Callbacks

Listing Subscriptions

List All Subscriptions

Endpoint

Example cURL Request

Example Response

List a Specific Subscription

Endpoint

Example cURL Request

Example Response

Unsubscribing

Delete a Subscription

Endpoint

Example cURL Request

Event Notifications