Event Notifications

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.

Subscribe to a Studio Project

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}"
   }
}

Subscribe to a File or Folder Within a Studio Project

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}"
   }
}

Subscribe to a Studio Session

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}"
   }
}

Subscribe to a Document Within a Studio Session

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

Event Notifications

Overview

Creating Subscriptions

• Studio Project
• Studio Project Folder or File
• Studio Session
• Studio Session Document
• Comprehensive Subscriptions

Listing Subscriptions

• List All Subscriptions
• List A Single Subscription

Unsubscribing