Smartsheet OpenAPI Reference (2.0.0)

A User in Smartsheet must have a primary email address associated with their user account (User.email) and may optionally have one or more alternate email addresses associated with their account (User.alternateEmails). The following operations must be performed using an user's primary email address:

• Add Group Members
• Add User
• Create Update Request
• Share Report
• Share Sheet
• Share Workspace

Attempting to specify a user's alternate email address for any of the above operations results in an error.

Attachments can exist on a comment (that is, within a discussion), on a row, or on a sheet.

Post an Attachment

Like the Smartsheet app, the Smartsheet API allows uploading files to sheets, rows, and comments.

You can upload a file by performing either a simple upload or a multipart upload.

A simple upload allows you to add a single file attachment to the specified object.

For example, you can perform a simple upload to attach a file to a sheet, attach a file to a row, or attach a file to a comment.

A multipart upload allows you to add a single file attachment to the specified object (that is, attach a file to a sheet, row, or comment), or to create an object and attach a file using a single request.

For example, you can perform a multipart upload to add a new comment that contains a single file attachment or to add a new discussion to a sheet that contains a single file attachment.

The max file size for uploads through the API is limited to 30mb.

NOTE: This is a resource-intensive operation. If you encounter an error, see Rate Limiting.

Multipart Uploads

A multipart upload request must include the following HTTP headers:

The request body of a multipart upload request contains one or more parts, each part containing either JSON or a file to upload.

The request body must contain at least one part.

Each part must start with the boundary string specified in the Content-Type request header, and must contain the following part headers:

The last part in the request must be followed by the boundary string, followed by two hyphens.

The documentation for each operation that supports multipart uploads specifies the number and names of parts that are expected for the operation.

File parts must have the part name "file", and documentation for operations which allow for JSON object parts specify the required part name for the JSON part.

The following example shows a multipart upload request that creates a comment containing the specified text and file attachment:

POST https://api.smartsheet.com/2.0/sheets/4509093797881732/discussions/2889925487028100/comments

Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Content-Length: 29008

Content-Type: multipart/form-data; boundary=----gU8h01zAAp3LagBr

------gU8h01zAAp3LagBr

Content-Disposition: form-data; name="comment"

Content-Type: application/json

{ "text": "Please review the attached image." }

------gU8h01zAAp3LagBr

Content-Disposition: form-data; name="file"; filename="picture.jpg"

Content-Type: image/jpeg

< Binary content for file >

------gU8h01zAAp3LagBr--

NOTE: Most programming languages have libraries that can be used to assemble multipart requests.

Simple Uploads

To perform this kind of upload, you must set specific headers to tell Smartsheet about the file. The following three headers are required:

The following example request shows a simple upload that adds a file attachment to a sheet:

POST https://api.smartsheet.com/2.0/sheets/4509093797881732/attachments

Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Content-Disposition: attachment; filename="ProgressReport.docx"

Content-Type: application/msword

Content-Length: 5463

< Binary content for file >

As shown in this example, the contents of the file is included in the body of the POST request. In most programming languages, this is done by reading the file from an input stream and writing it out to the output stream of the HTTP request.

Automation is a catch-all term for approvals, notifications, and update requests. You can delete, update, or retrieve various automation settings through the API. You cannot create new automation rules programmatically.

Disabled Reasons for Automation Rules

A cell image is an image that has been uploaded to a cell within a sheet.

A collection of cells comprises each row in a sheet.

Cell Links

Creating or updating cell links via the cell.linkInFromCell attribute is a special operation. A given row or cell update operation may contain only link updates, or no link updates. Attempting to mix row/cell updates with cell link updates results in error code 1115. Additionally, a CellLink object can only be added to an existing cell, so the cell.linkInFromCell attribute is not allowed when POSTing a new row to a sheet.

When creating a cell link, cell.value must be null (the data is pulled from the linked cell).

A cell may not contain both a hyperlink and a cell link, so hyperlink and linkInFromCell may never both be non-null at the same time.

Cell Reference

Cell Value Representation

Cell objects retrieved through the Smartsheet APIs have two main attributes representing cell values: Cell.value, and Cell.displayValue. A third attribute, Cell.objectValue is currently used only for adding and updating predecessors, or for multi-contact or multi-picklist details, such as email addresses or values in a multi-picklist. An empty cell returns no value.

Cell.displayValue is always a string and is only returned for certain column types (see below). It represents the formatted value as it should be displayed to an end-user. For example, if a TEXT_NUMBER column is formatted as a US Dollar currency, its value may be a number like 1234.5678, but its displayValue is "$1,234.57".

Cell.value represents a cell's raw value and can be one of the following primitive JSON types: string, number, or Boolean, depending on the column type. An empty cell returns no value. Complex types are represented as strings, formatted as described below:

Help with Project Columns

Cell.objectValue is an object representation of a cell's value and is currently used for adding or updating predecessor cell values, or for multi-contact details, such as email addresses.

• For predecessors, it provides a more "programmer friendly" format for assembling predecessors. To update a cell's predecessors, set objectValue to a PredecessorList object containing Predecessor objects.
• For multi-contact or multi-picklist details, use both a level query parameter and an include=objectValue query to see email addresses rather than display names or to see multi-picklist values.

Cell Value Parsing

The flexibility in cell value data types is a powerful feature in the Smartsheet application; however, it poses a challenge for an API in terms of parsing. Being too flexible might result in unexpected behavior. For instance, if you write code to post a Date value to a Smartsheet and the API operation succeeds, you might assume that the date value you sent was interpreted as date. What happens if you posted your date in the wrong format? Do you really want Smartsheet to keep the malformed date as a string value? Probably not.

To address this problem, the Smartsheet API employs a simple scheme to indicate whether you want a more predictable and strict interface or a more flexible one. By default, a cell value is expected to conform to "strict" rules for the type of the cell's column. If an input value doesn't conform, the API returns error code 1042.

If, however, you want the same flexibility as the Smartsheet Web app, you can disable the strict rules, and we'll do our best to make sense of it. To enable lenient parsing simply include "strict": false in the Cell object in your request body.

NOTE: How does strict cell value parsing compare to cell validation settings? Strict cell value parsing determines how string values are parsed. It is set on a per-call basis. In contrast, cell validation is part of the column definition. The overrideValidation property is restricted to sheet admins and does not override strict parsing.

The parsing rules for the various column types are as follows:

ABSTRACT_DATETIME

CHECKBOX

CONTACT_LIST

NOTE: See the Contact List Columns section for more information.

DATE

DURATION

NOTE: You may use the query string parameter projectParseLocale with a supported locale string to force parsing in the specified locale (for example, using en_US lets you send in English values regardless of the user's locale).

MULTI_CONTACT_LIST

MULTI_PICKLIST

PICKLIST

PREDECESSOR

TEXT_NUMBER

NOTE: The Smartsheet application only supports numeric values in the range -9007199254740992 to 9007199254740992. If using strict parsing, any numeric value outside that range results in error code 1148. If using lenient parsing, the value is silently converted to text.

Contact List Columns

With columns of type CONTACT_LIST, the cell attributes value and displayValue are treated independently. The contact's email address is represented by value, while the contact's name (and the value displayed in the cell in the Smartsheet app) is represented by displayValue.

When creating or updating cells for a contact list column, the displayValue attribute works as follows:

• If displayValue is non-null and non-empty, the Smartsheet cell displays the value provided.
• If displayValue is an empty string, the Smartsheet cell displays the email address.
• If displayValue is null or absent, Smartsheet makes a best guess effort at filling it in with a contact's name based on the email address.

Hyperlinks

You can create and modify hyperlinks by using any API operation that creates or updates cell data. When creating or updating a hyperlink, cell.value may be set to a string value or null. If null, the cell's value is derived from the hyperlink:

• If the hyperlink is a URL link, the cell's value is set to the URL itself.
• If the hyperlink is a dashboard, report, or sheet link, the cell's value is set to the dashboard, report, or sheet name.

Images in Cells

For details about working with images in cells, see Cell Images.

A column is a component of a sheet or report.

Column Types

Smartsheet supports the following standard column types, which are represented in a Column object with a type attribute set to one of the following:

NOTE: See the Cell Reference section for information on getting and setting cell values for the different column types.

Symbol Columns

In addition to the basic column types above, the Smartsheet app also supports columns that display symbols. These are specialized columns of type CHECKBOX or PICKLIST, whose symbol attribute is set to one of the values below:

Symbols for CHECKBOX columns:

Value	Example
FLAG
STAR

Symbols for PICKLIST columns:

Value	Example
ARROWS_3_WAY
ARROWS_4_WAY
ARROWS_5_WAY
DECISION_SHAPES
DECISION_SYMBOLS
DIRECTIONS_3_WAY
DIRECTIONS_4_WAY
EFFORT
HARVEY_BALLS
HEARTS
MONEY
PAIN
PRIORITY
PRIORITY_HML
PROGRESS
RYG
RYGB
RYGG
SIGNAL
SKI
STAR_RATING
VCR
WEATHER

NOTE: The Smartsheet grid user interface presents several row attributes and features visually as columns, for example, attachments, discussions, row action indicator, or row number. The API does not consider these to be columns, and does not return or otherwise expose them as columns. The only columns returned by the API are user data columns.

System Columns

In addition to the standard column types and symbols, Smartsheet has a number of system columns, which represent data that is filled in by Smartsheet and whose values cannot be changed by the user. These columns are represented with standard column types, with the Column.systemColumnType attribute set to one of the following:

A discussion is a container for a number of individual comments in a threaded conversation. For more details, see the Discussion section.

This section describes operations on an individual comment within a discussion thread.

• To retrieve all discussions and comments for an entire sheet, use List Discussions with the query parameter include=comments.

• To retrieve all discussions and comments associated with a row, use List Row Discussions with the query parameter include=comments.

A comment can contain one or more attachments.

Comment Attachments

For details about working with a comment's attachments, see Attachments.

A contact is a user's personal contact in Smartsheet (as described in the Help Center article, Managing Contacts.

To create a formula that references data in another sheet, you must first create a cross-sheet reference between the detail sheet and the source sheet. That reference must also define the cell range. Once you have created the cross-sheet reference, you can use the reference name in any formula on the detail sheet. To create the formula, use Add Rows or Update Rows. Cross-sheet references that are not used by any formula are automatically deleted after two hours.

Smartsheet dashboards are a collection of widgets that can contain data from a variety of different data sources (for example, sheets, reports, or custom data). Dashboards were once called Sights(TM) and this name is still present in object names, endpoint paths, and other places.

A discussion is a container for a collection of individual comments within a single thread. A discussion can exist on a row or a sheet.

In the UI, Smartsheet creates a discussion to contain each top-level comment and subsequent replies into a single thread.

Using the API, you can only add a comment to a discussion. If the discussion doesn't already exist, you must create it first. A discussion is a collection of one or more comments, each of which may contain attachments.

Discussion Attachments

For details about working with the attachments within a discussion, see Attachments.

Discussion Comments

For details about working with a discussion's comments, see Comments.

Smartsheet uses event objects to capture actions such as creating, updating, loading, deleting, and more for items such as sheets, reports, dashboards, attachments, and users. With Event Reporting, you can use the operations described here to programmatically retrieve these events.

NOTE: Event Reporting is a premium add-on available for Enterprise and Advanced Work Management plans only. For details on the add-on, please contact our Sales Team.

Event types

All events derive from the Event schema. Each event type overrides Event's objectType and action properties with its specific object type and a typical action performed on that object. Furthermore, each event type's additionalDetails object has properties specific to the event type.

See Event types for the complete event listing, details, and example objects.

System users

System components perform some actions in Smartsheet. Therefore, the userId property in some response payloads refers to a system user--not to a regular user. For example, the Smartsheet Events API shows 5629504736520068 as the userId when an anonymous user accesses a sheet that is published for anyone.

The system users are listed below. New system userIds may be incorporated to this list as new features and subsystems are incorporated to Smartsheet:

Smartsheet allows users to "star" dashboards, folders, reports, sheets, workspaces, and other objects on their Home tab to mark them as favorites. These API operations allow you to access the user's favorite API-supported objects, as well as create and delete favorites. NOTE: For documentation purposes, "favoriteType" is a placeholder ENUM for the various types of UI elements you can flag as a favorite. In sample code, when you see "{favoriteType}", just replace it with one of the following values:

• dashboard or dashboards (aka Sight or Sights)
• folder or folders
• report or reports
• sheet or sheets
• template or templates
• workspace or workspaces

A folder can exist in a user's Sheets folder Home, in a folder, or in a workspace.

A group member is a user that belongs to a group.

A group is a collection of group members.

In the Smartsheet UI, the "Home" tab shows all objects a user has access to, including dashboards (also called Sights in the API), folders, reports, sheets, templates, and workspaces.

NOTE: The GET /home endpoint is deprecated. Use GET /folders/personal to get shared items and GET /workspaces/ to get workspaces.

Home Folders

For details about working with folders in the user's Sheets folder (that is, at the Home level), see Folders.

Home Sheets

For details about working with sheets in the user's Sheets folder (that is, at the Home level), see Sheets.

Import CSV or XLSX data into a new sheet.

A proof is a container that holds attachments and comments. Limited to one proof and its versions per row. A sheet can have multiple proofs.

A report is a filtered view of the data from one or more sheets. Like a sheet, a report is comprised of columns, rows, and cells, and may optionally contain attachments and discussions. A report is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

Report Attachments

For details about working with a report's attachments, see Attachments.

Report Cells

For details about working with a report's cells, see Cells.

Report Columns

For details about working with a report's columns, see Columns.

Report Discussions

For details about working with a report's discussions, see Discussions.

Report Rows

For details about working with a report's rows, see Rows.

A row is a component of a sheet or report. Each row is composed of a collection of cells, and may optionally contain discussions or attachments.

A row is comprised of a collection of cells, and may optionally contain attachments and discussions.

Row Attachments

For details about working with a row's attachments, see Attachments.

Row Cells

For details about working with a row's cells, see Cells.

For details about working with images in cells, see Cell Images.

Row Discussions

For details about working with a row's discussions, see Discussions.

Row Include Flags

Endpoints which return rows (for example, Get Sheet, Get Row) support the optional include query string parameter. If specified, the value of the include parameter is a comma-delimited list of flags that indicate additional attributes to be included in each Row object within the response.

Specify Row Location

When you add a row, the default behavior is for Smartsheet to put the new row at the bottom of the sheet. And when you update a row, the default behavior is to keep the row where it is. It is not necessary to use a location-specifier attribute if you want the default behavior.

To specify a location for new or updated rows other than the defaults, use the table below for reference. The table details possible row locations and provides JSON examples to help you construct one or more Row objects with location-specifier attributes.

Note the following restrictions:

• Use only one location-specifier attribute per request, unless you use parentId and toBottom or siblingId and above.
• If you specify multiple rows in the request, all rows must have the same location-specifier attributes.
• If you specify the parentId attribute, you cannot also specify the siblingId attribute.
• If you specify the siblingId attribute, you cannot also specify the parentId, toTop, or toBottom attributes.
• If you want to indent or outdent multiple rows, use the parentId attribute.

Search a specific sheet or search across all sheets that a user can access. If you have not used the public API in a while, we will need to provision your data. This could take up to 24 hours so please check back later!

The methods for sending via email rely on the type of object you want to send.

Send Report

For details about sending a report via email, see Send Report via Email.

Send Rows

For details about sending rows via email, see Send Rows via Email.

Send Sheet

For details about sending a sheet via email, see Send Sheet via Email.

Send Update Request

For details about sending an update request via email, see Create an Update Request.

For developer convenience, the Smartsheet API provides access to application constants.

Use the Sharing operations to control sharing of dashboards, reports, sheets, and workspaces.

A sheet summary allows users to define, organize, and report on custom project and business metadata. Sheet summary is only available to customers with business or enterprise plans.

A sheet can exist in a user's Sheets folder (Home), in a folder, or in a workspace. It is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

A sheet is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

Sheet Attachments

For details about working with a sheet's attachments, see Attachments.

Sheet Cells

For details about working with a sheet's cells, see Cells.

For details about working with images in cells, see Cell Images.

Sheet Columns

For details about working with a sheet's columns, see Columns.

Sheet Discussions

There are two ways to get discussion-related information for a sheet:

For more information about working with a sheet's discussions, see Discussions.

Sheet Rows

For details about working with a sheet's rows, see Rows.

A template can be used to create a sheet, as described for the Create sheet in folder endpoint and the Create sheet in workspace endpoint.

The Smartsheet API utilizes OAuth 2.0 for authentication and authorization. An Authorization HTTP header containing an access token is required to authenticate all API requests except for the requests to GET Access Token or Refresh Access Token. For more information, see Authentication.

Send update requests to get updated by any collaborator on key rows, regardless of whether they have a Smartsheet account or are shared to the sheet.

Users are typically defined by the organization account, and then role within the organization, for example admin.

Webhooks introduction

At a high-level, here's how our webhooks work:

1. Your application subscribes to callbacks.
   First, subscribe to event notifications (callbacks) by creating one or more webhooks. You can create a webhook manually via the API or have your application create a webhook dynamically. Each webhook must specify:

   • Which Smartsheet object to monitor for events

   • Which events in that object should trigger a callback

   • The HTTPS URL (that is, "callback URL") where Smartsheet should send callbacks when any of the specified events occur within the scope of the specified Smartsheet object. (NOTE: Smartsheet webhooks do not support callbacks to servers using self-signed certificates)

     Webhook examples in plain English:

     • "When any changes occur in Sheet_A, send a callback to https://www.example.com/abc"
     • "When a new row is added to Sheet_B, send a callback to https://www.example.com/def"
     • "When a cell value is changed in Sheet_C, send a callback to https://www.example.com/ghi"

2. When any of the specified events occur within an object that is being monitored by a webhook, Smartsheet sends an HTTP POST (that is, a "callback") to the callback URL that is associated with the webhook.

   NOTE: The callback payload is a "skinny" payload -- it indicates which objects changed and the type of events that occurred, but does not contain any data from the objects themselves.

3. Your application receives, acknowledges, and processes callbacks.
   Your application receives the HTTP POST, acknowledges the callback by responding with HTTP status 200, and processes the callback. Because the callbacks are "skinny", you can make additional Smartsheet API requests to retrieve the actual data associated with the event.

You manage your webhooks using the webhooks endpoints described in this section.

Webhook Ownership & Access

IMPORTANT: Webhooks are automatically disabled on sheets that exceed 20,000 rows, 400 columns, or 500,000 cells (whichever comes first). Stay within the specified limits to keep webhooks enabled on your sheets.

Webhooks can be created and managed via direct API access or by a third-party application.

A webhook that is created via Direct API Access:

• is owned by the user who created it
• can be managed only by the user who created it
• is not affected if the access token that was used to create it is revoked, as long as the user remains active

A webhook that is created by a third-party app:

• is owned by the user who authorized the third-party app (and is associated with the third-party app)
• can be managed by the third-party app (as long as it maintains authorization) or by the user who owns it
• is permanently disabled if the third-party app's permissions are revoked

Webhook Scope & Events

A webhook monitors the specified scope for the specified events.

A Webhook object's scope attribute indicates the scope of the subscription. It is specified when creating a webhook (see Creating a Webhook, below), and cannot subsequently be changed.

• Currently, sheet is the only supported value for the scope attribute. However, you can set an array of columns as a subscope if you want to limit the webhook to specific columns.

A Webhook object's event attribute indicates the set of events that a webhook is subscribed to (that is, which events trigger a callback).

• Events are represented as a dot-separated string in the format "object.event", where an asterisk (*) can be used to represent "all objects" or "all events".
• Currently, *.* is the only supported value for the events attribute. This indicates a subscription to all objects in the scope, and all events for those objects.

NOTE: When a row is deleted on a sheet, even if you are using a subscope to monitor columns only and the cell in that column for that row is empty, you will receive a "row.deleted" event.

Example

Consider a Webhook object with the following attribute values:

• scopeObjectId = 12345678901234
• scope = "sheet"
• events = "*.*"

This webhook monitors the specified sheet (id: 12345678901234) for all types of events. For example, if a row is added to the sheet, cell values are updated in the sheet, a column is deleted from the sheet, etc., a callback is sent to the webhook's callbackUrl.

Creating a Webhook

An API client can create a webhook by using the Create Webhook operation. A newly created webhook is disabled by default. After successfully creating a webhook, the API client must subsequently initiate and complete the verification process (see Webhook Verification below) before the webhook is enabled. The following diagram illustrates the process of creating and enabling a webhook.

Step-by-Step

The process occurs synchronously:

1. API client submits a Create Webhook request.

2. Smartsheet creates the webhook, but does not initially enable the webhook (enabled: false and status: "NEW_NOT_VERIFIED").

3. To initiate the verification process, the API client submits an Update Webhook request to specify enabled: true. (NOTE: The API client does not receive a response to this request until the verification process (steps 4 and 5) has completed.)

4. When Smartsheet receives the request to enable the webhook, it sends a verification request (see the Webhook-Verification section) to the subscriber (that is, to the callbackUrl that the API client specified in the Create Webhook request). The request specifies a unique random value in the Smartsheet-Hook-Challenge header and contains only challenge and webhookId in the request body. The challenge value is a repeat of the header value for API clients that don't interpret header values.

5. The subscriber responds to the verification request by echoing back the same unique random value in the Smartsheet-Hook-Response header of the response. For API clients that don't interpret header values, you can also send a JSON body with a smartsheetHookResponse attribute and the same value that would have been in the header.

6. Once the subscriber has successfully acknowledged the verification request, Smartsheet enables the webhook and responds to the API client's Update Webhook request to confirm that the webhook has been enabled (enabled: true and status: "ENABLED").

Webhook Verification

When an API client attempts to enable a webhook, Smartsheet sends a verification request to the webhook's callbackUrl to verify that the subscriber expects and is able to successfully receive callbacks. The request specifies a unique random value in the Smartsheet-Hook-Challenge header and contains a JSON object in the request body with only challenge and webhookId attributes in the request body. The challenge attribute is a repeat of the header value for API clients that don't interpret header values.

• To verify the webhook, the subscriber's response to the verification request must return a 200 HTTP status code and must echo back the same unique random value in the Smartsheet-Hook-Response header of the response or with a JSON smartsheetHookResponse attribute. Once Smartsheet receives this verification response, the webhook is enabled (enabled: true and status: "ENABLED").

• If the subscriber does not successfully respond to the verification request, the webhook remains disabled (enabled: false and status: "DISABLED_VERIFICATION_FAILED").

When a webhook is initially created through the API, the response contains the webhook's Id. If you wish to guarantee that your server only receives callbacks for webhooks that you created, you can check the verification request's webhookId attribute against your list of created webhook Ids. If the Id is not in the list, return a response with a non-200 status code (for example, 403 Forbidden), and the webhook that initiated the verification request is disabled as described above.

NOTE: IMPORTANT: ONGOING VERIFICATION. Once a webhook has been enabled, Smartsheet sends a verification request to the webhook's callbackUrl once every 100 callbacks. The subscriber should respond to the verification request as described above -- failure to do so results in the webhook being disabled (enabled: false and status: "DISABLED_VERIFICATION_FAILED").

Duplicate Webhooks

Duplicate webhooks are defined as two or more webhooks that meet the following conditions:

• on the same sheet
• created by the same user
• have identical: callbackUrl and subscope properties.

Because duplicate webhooks are functionally identical, this would ordinarily result in the callback URL being called simultaneously once for each duplicate webhook in the sheet when the sheet changes. Many duplicates can lead to too much traffic which can cause a denial of service (DOS) on the callback server.

There are no known valid use cases for duplicate webhooks; they are usually created unintentionally by API clients due to faulty or missing logic.

For this reason, as of January 2023, Smartsheet will now deduplicate webhook callbacks. This means for every set of duplicate webhooks on a sheet, Smartsheet will no longer issue one callback per webhook, and will instead only issue one total callback, for only the oldest enabled webhook.

Recommendation: When creating a webhook, first check to make sure that the sheet doesn't already contain an identical webhook. If it does, and it's disabled, re-enable it. If it's already enabled, do nothing.

Webhook Status

A Webhook object's enabled attribute indicates whether a webhook is enabled or disabled, while the status attribute describes the reason that the webhook is enabled or disabled.

The following table lists all possible combinations of enabled and status attribute values.

NOTES:

• When a Webhook object's enabled attribute is set to true, Smartsheet is monitoring for the specified events and sends a callback (see the Event Callbacks section) to the callbackUrl when the events occur.
• When a Webhook object's enabled attribute is set to false, Smartsheet is not monitoring for the specified events and does not send a callback to the callbackUrl when the events occur. Depending on the value of the status attribute, it may be possible to (re-)enable the webhook. (See below for details).

Webhook Callbacks

A callback is the notification that Smartsheet sends to a webhook's callbackUrl. There are two types of callbacks:

• Event callback (see the Event Callbacks section): Alerts the subscriber when the specified events have occurred in Smartsheet. This is the most common type of callback.

• Status Change callback (see the Status Change Callbacks section): Alerts the subscriber that a webhook has been automatically disabled due to loss of access or automatically re-enabled due to restoration of access.

A Subscriber has the ability to verify the integrity of a callback payload (that is, ensure that the message was not tampered with en route) and authenticate the identity of its sender (that is, ensure that the callback did indeed originate from Smartsheet). For more information, see Authenticating Callbacks (see the Authenticating Callbacks(optional) section).

NOTES:

• Smartsheet webhooks do not support callbacks to servers using self-signed certificates. The callback server must be using a signed certificate from a certificate authority.
• The callbackURL cannot be a private IP address.
• The callbackURL must use one of the following ports: 443 (default for HTTPS), 8000, 8008, 8080, or 8443.
• Smartsheet webhooks alway let a running callback for a given sheet finish before making another, that is the second call will wait on the first one to finish.

Event Callbacks

Smartsheet sends an event callback to notify the subscriber when the specified events occur in Smartsheet.

WARNING: Any events that occur while a webhook is disabled are not communicated via callback if/when webhook is enabled.

IMPORTANT: For Smartsheet US and Smartsheet Regions Europe since October 14th 2024, a one-minute debounce was introduced to optimize event trigger handling in the Webhooks event callback API. It reduces traffic and prevents workflows from acting on incomplete or transitional data.

Callback Acknowledgement

The subscriber must respond to an event callback with a 200 HTTP status code to acknowledge that the callback was received.

Retry Logic

If the subscriber fails to respond with a 200 status, depending on the response, Smartsheet may retry delivery up to 14 times. (The first 7 retry attempts occur with a frequency that's determined using exponential backoff; thereafter, retry attempts occur once every three hours until all retries have been exhausted.)

If the response is not retriable or retry attempts have been exhausted, the webhook is disabled (enabled: false and status: "DISABLED_CALLBACK_FAILED"). A webhook in this state can be re-enabled if the subscriber completes the verification process. (See the Webhook Status section for details.)

Status Change Callbacks

If a webhook's owner loses access to the object that a webhook is monitoring (either because the object was deleted or the webhook owner's access to the object was revoked in Smartsheet), Smartsheet automatically disables the webhook and sends a status change callback to alert the subscriber of this change in status. The newWebhookStatus attribute indicates that the webhook is now disabled (because the scope is inaccessible).

If the webhook owner's access to the object is subsequently restored, Smartsheet automatically re-enables the webhook and sends a status change callback to alert the subscriber of this change in status. The newWebhookStatus attribute indicates that the webhook is now enabled.

Authenticating Callbacks (optional)

A subscriber has the ability to verify the integrity of a callback payload (that is, ensure that the message was not tampered with en route) and authenticate the identity of its sender (that is, ensure that the callback did indeed originate from Smartsheet).

When you create a new webhook, it is assigned a randomly generated sharedSecret value. The shared secret is used by Smartsheet to sign callback payloads, and should not be shared with any third parties.

To authenticate a callback request:

1. Calculate the HMAC of the webhook's sharedSecret and the request body. This must be done using the SHA-256 cryptographic hash algorithm.

2. Format the calculated value as a string in base 16.

3. Compare your result with the value of the Smartsheet-Hmac-SHA256 header of the request.

If the values match, you can be sure the request originated from Smartsheet and that the data has not been tampered with.

NOTE: For maximum security, you may also choose to reset your webhook's shared secret at periodic intervals.

Preventing Infinite Loops

It's possible that an application which subscribes to callbacks (using webhooks) might react to those callbacks by using the API to make additional changes in Smartsheet. But, consider the following scenario:

1. App1 creates a webhook to monitor Sheet-A for changes, specifying an App-1 URL as the callbackUrl for the webhook.

2. App-1 updates Sheet-A using the API.

3. Smartsheet detects that Sheet-A has changed and sends a callback to App-1 (as the webhook specified).

4. App-1 processes the callback, and in the course of doing so, updates Sheet-A again using the API.

5. Return to Step 3.

To protect against infinite loops like the one outlined above, Smartsheet introduced support for a new header that an API client can include with any API request that adds, updates, or deletes data in Smartsheet. Here's how it works:

• An API client includes the Smartsheet-Change-Agent header in any API request that adds, updates, or deletes data in Smartsheet.
  • The header value should be set to a string that the API client recognizes as identifying itself.
• If any event callbacks fire as a result of an API request that contains the Smartsheet-Change-Agent header, the value of the Smartsheet-Change-Agent header is included in the callback in the value of the changeAgent attribute.
• If a webhook subscriber receives a callback that contains the changeAgent attribute, it should evaluate the attribute value:
  • If the attribute value's comma-delimited list contains the subscriber API client's change agent value, this indicates that the change which triggered the callback was caused by the subscriber itself, and the subscriber can choose to ignore the callback, thus preventing an infinite loop.
  • Else, the change which triggered the callback was not caused by the subscriber itself, and if the subscriber is going to subsequently react to the callback by making a change in Smartsheet (via API request), the API client should append a comma and its own identifier to the original attribute value, and pass that value through using the Smartsheet-Change-Agent header of the API request. Doing so protects against cross-system infinite loops.

NOTE: The Smartsheet-Change-Agent header value has a maximum length of 512 characters. If its length exceeds 512 characters, the excess is trimmed from the front of the string, so that the most recent agent information remains.

Webhook Errors

The following table specifies the recommended action for each Smartsheet-specific error code. Use this information to implement error handling logic according to the following guidelines:

• If the error code indicates a permanent error condition, do not retry the request.
• If the error code indicates a problem that can be fixed, do not retry the request until the problem has been fixed.
• If the error code indicates a problem that could be overcome by retrying the request after a period of time, retry the request using exponential backoff.

Similar to a folder, a workspace is a place where you can store dashboards, reports, sheets, and templates to keep them organized. A workspace offers more functionality than a folder because you can set up sharing permissions and branding (a logo and a color scheme) at the workspace-level and a workspace can contain folders so that you can keep things within it organized. As new items are added to the workspace, they'll automatically inherit the sharing permissions and branding applied to that workspace.

Workspace Folders

For details about working with folders in a workspace, see Folders.

Workspace Sheets

For details about working with sheets in a workspace, see Sheets.