With the March 2016 release, we’re pleased to announce public availability of Webhooks (beta), as well as several new endpoints and objects and a number of enhancements to existing endpoints and objects - to support new product features and functionality.

 

 


Release Highlights

Highlights of this release include:

  • Webhooks are now in public beta - and available to all Smartsheet customers.  The complete Webhooks documentation is now included in our API docs.
  • New endpoints & objects as well as updates for existing ones to support new product features, including Sights, Workspace External Sharing, Granular Publishing Permissions, and OneDrive integration.

  • API enhancement that adds createdAt and modifiedAt parameters to the Share object.

  • New OAuth2 access scopes to support the new Sights feature.

  • Bug fix to eliminate a possible race condition in the token refresh flow..

 

 

Webhooks

Smartsheet Webhooks are here!  We have completed our private beta and Webhooks are now available to all Smartsheet customers.  Please note, however, that the feature is still in beta.  This means that you may still experience stability and performance issues, and we reserve the right to make breaking changes before we release into production.

 

First, make sure to read up on how our Webhooks work - see our detailed Webhooks documentation.  Pay particular attention to the verification requirements and flow - we take it a step further than most webhook implementations.  We recognize that this may require additional development effort (hopefully, small), but we have made a decision to follow security best practices to ensure we are good netizens and protect our customers.  The other important thing to keep in mind is that our webhook notification payloads are what's called "skinny" - they will let you know which objects have changed, but will not include the actual data changes.
Webhooks Endpoints

Operation

HTTP Method

Endpoint

List webhooks

GET

/webhooks

Get webhook

GET

/webhook/{webhookId}

Create webhook

POST

/webhooks

Update webhook

PUT

/webhook/{webhookId}

Delete webhook

DELETE

/webhook/{webhookId}

Reset shared secret

POST

/webhook/{webhookId}/resetsharedsecret

 

Webhooks Objects

 

Operation

HTTP Method

Endpoint

List webhooks

GET

/webhooks

Get webhook

GET

/webhook/{webhookId}

Create webhook

POST

/webhooks

Update webhook

PUT

/webhook/{webhookId}

Delete webhook

DELETE

/webhook/{webhookId}

Reset shared secret

POST

/webhook/{webhookId}/resetsharedsecret

 


New API Endpoints

The following new endpoints have been added to API 2.0:

 

Operation

HTTP Method

Endpoint

List Sights

GET

/sights

Get Sight

GET

/sights/(sightId}

Update (rename) Sight

PUT

/sights/(sightId}

Delete Sight

DELETE

/sights/(sightId}

Copy Sight

POST

/sights/(sightId}/copy

Move Sight

POST

/sights/(sightId}/move

List Sight Shares

GET

/sights/(sightId}/shares

Get Sight Share

GET

/sights/(sightId}/shares/{shareId}

Share Sight

POST

/sights/(sightId}/shares

Update Sight Share

PUT

/sights/(sightId}/shares/{shareId}

Delete Sight Share

DELETE

/sights/(sightId}/shares/{shareId}

 


Updated API Operations

The following existing operations have been updated:  

 

Operation

Change(s)

Attach URL (to: Comment | Row | Sheet)

Now supports adding a URL attachment from OneDrive (attachmentType = ONEDRIVE)

Get Sheet Publish Status

Now returns information about who has access to the published view(s) of the Sheet (new attributes:  readOnlyFullAccessibleBy, readWriteAccessibleBy)

Get Report Publish Status

Now returns information about who has access to the published view of the Report (new attribute:  readOnlyFullAccessibleBy)

List Sheet Shares

Now supports getting either just sheet-level shares (default behavior) or BOTH sheet-level shares AND workspace-level shares (via new query string parameter: if "include=workspaceShares" is specified, the response will contain both sheet-level shares and workspace-level shares)

List Report Shares

Now supports getting either just report-level shares (default behavior) or BOTH report-level shares AND workspace-level shares (via new query string parameter: if "include=workspaceShares" is specified, the response will contain both report-level shares and workspace-level shares)

Set Sheet Publish Status

Now provides the ability to more tightly control who can access the published view(s) of a Sheet (via new attributes:  readOnlyFullAccessibleBy, readWriteAccessibleBy)

Set Report Publish Status

Now provides the ability to more tightly control who can access the published view of a Report (via new attribute:  readOnlyFullAccessibleBy)

Share Sheet

Now enables you to share a Sheet that resides in a workspace (previously, an error would have been returned if you tried to share a Sheet that resided in a workspace)

Share Report

Now enables you to share a Report that resides in a workspace (previously, an error would have been returned if you tried to share a Report that resided in a workspace)

Add Favorite(s)

Now support new Favorite.type = sight

List Favorites

Now returns Favorite objects of Favorite.type = sight

Remove Favorite Sight or Sights

Removes one or more Sights from the user’s list of Favorite items

List All Contents

The /home endpoint now includes an array of Sights under the "sights" property

Get Folder, Get Workspace

The Folder object now returns an array of Sights under the "sights" property

Copy Folder, Copy Workspace

Now supports new skipRemap parameter value: “sight”

Search Everything

Now supports returning SearchResultItem(s) of type SearchResultItem.objectType = sights


 

New API Objects

To facilitate the new endpoints and API enhancements described above, the following new objects have been added:

 


Updated API Objects

To facilitate the new endpoints and API enhancements described above, the following objects have been updated:

 

Object

Change(s)

Attachment

New ENUM value for attachmentType: ONEDRIVE

Share

New attributes: scope, createdAt, modifiedAt

SheetPublish

New attributes:  readOnlyFullAccessibleBy, readWriteAccessibleBy

ReportPublish

New attribute:  readOnlyFullAccessibleBy

Hyperlink

New attribute: sightId


 

New API Access Scopes

The following OAuth2 access scopes have been added to support the new Sights feature:

  • READ_SIGHTS

  • CREATE_SIGHTS

  • ADMIN_SIGHTS

  • DELETE_SIGHTS

  • SHARE_SIGHTS

 

Bug fix

We identified and eliminated a possible race condition during the token refresh process - which could have led to a recently generated refresh token being quickly rendered invalid.

 


What now?

If you’re already using API 2.0 or are building a new integration,  you can start taking advantage of these API enhancements right away.  Changes to existing endpoints are non-breaking and backwards-compatible with API 2.0.  See the Smartsheet API 2.0 documentation for comprehensive information about our API, and check out the Smartsheet Developer Portal for additional resources to help you along the way.

 

If you’re still using API 1.1, we strongly recommend upgrading your integration to API 2.0 so that you can take advantage of the new features and functionality.  It’s now been over 6 months since we announced the deprecation of API 1.1 -- you should upgrade to API 2.0 now to avoid any disruption when API 1.1 is discontinued on July 31, 2016.  See the API 2.0 Release Notes for helpful information about migrating from API 1.1 to API 2.0.

 

As always, we’re here to support you - if you have feedback about API 2.0, questions about migrating from API 1.1 to API 2.0, ideas about new features, or run into an issue using the API, ping us at api@smartsheet.com.


 

- The Smartsheet Platform Team

Categories

Add new comment