Guides
/
Webhooks
/
Launch a webhook
Last updated

Launch a webhook

Smartsheet webhooks subscribe you to receive notifications of events you want to an endpoint location you specify.

This tutorial demonstrates how to create a Smartsheet webhook and enable it to start receiving event notifications.

Requirement

You must have an event-handling endpoint - Although it isn't required to create a webhook, it is required to enable your webhook and receive notifications. If you haven't created an endpoint for your webhook, see Create an event-handling endpoint.

Create your webhook

Here are instructions on how to create a webhook via the POST /webhooks operation.

This example, demonstrates creating a webhook that subscribes to notifications on new rows added to a sheet.

Note: You can apply the demonstrated principles to creating webhooks for other event types.

Construct a request body

Here is a request body for creating a webhook that subscribes to new sheet row events.

Request body:

{
  "name": "My New Sheet Rows",
  "scope": "sheet",
  "scopeObjectId": 3285357287499652,
  "events": ["*.*"],
  "version": 1,
  "callbackUrl": "https://www.myApp.com/my-sheet-webhook"
}

Here's a description of the parameters and their values:

  • name is the arbitrary name for the webhook. This one is named "My New Sheet Rows".
  • scope specifies the type of object ("sheet") that contains the object (row) affected by the event of interest (created).
  • scopeObjectId is the ID of the specific scope object.
  • events is a regular expression for filtering on events in the scope. Currently, Smartsheet webhooks only accept the following expression: "[*.*]" -- it represents all events in the scope.
  • version is the version of the webhook API, which is 1.
  • callbackUrl is the location of the event-handling endpoint.

Tip: If you haven't yet created your event-handling endpoint or determined its URL, you can assign callbackUrl to a dummy value for now and update the webhook with your endpoint's URL later.

Call the POST /webhooks endpoint

Call the POST /webhooks endpoint operation (see Create webhook) however you like, specifying your request body and all required headers.

Tip: You can call the operation using the query editor on this site. Just go to the Create webhook page and click the Try it button below the example request. In the editor that appears, you can specify your API token and parameters, send requests, and exmine responses instantly.

Here's how you can create the webhook from your command line using cURL. (Make sure to replace YOUR_API_TOKEN with your API token value.)

curl https://api.smartsheet.com/2.0/webhooks \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{   
  "name": "My New Sheet Rows",
  "scope": "sheet",
  "scopeObjectId": 3285357287499652,
  "events": ["*.*"],
  "version": 1,
  "callbackUrl": "https://www.myApp.com/my-sheet-webhook"
}'

Smartsheet creates the webhook and returns a response like the one below.

{
  "version": 3,
  "failedItems": [],
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "callbackUrl": "https://www.myApp.com/my-sheet-webhook",
    "events": [
      "*.*"
    ],
    "name": "My New Sheet Rows",
    "scope": "sheet",
    "scopeObjectId": 3285357287499652,
    "subscope": {},
    "version": 1,
    "enabled": false,
    "id": 8444254503626628,
    "apiClientId": "555555",
    "apiClientName": "Awesome Smartsheet Application",
    "createdAt": "2024-08-24T14:15:22Z",
    "disabledDetails": "",
    "modifiedAt": "2024-08-24T14:15:22Z",
    "sharedSecret": "216ejjzdnq17mq1q8xs7d4hu8b",
    "stats": {
      "lastCallbackAttempt": "2024-08-24T14:15:22Z",
      "lastCallbackAttemptRetryCount": 0,
      "lastSuccessfulCallback": "2024-08-24T14:15:22Z"
    },
    "status": "NEW_NOT_VERIFIED"
  }
}

The response includes the following notable pieces of information for this example.

  • "version": 3 - This is the current version of the sheet with the added row.
  • "result.id": <integer> - This is your new webhook's unique identifier. Record the ID value for enabling your webhook and for other optional purposes.
  • "result.enabled": false - New webhooks aren't initially enabled. Smartsheet enables each webhook only after the webhook passes the verification challenge process. You initialize that process next.
  • "result.status": "NEW_NOT_VERIFIED" - This is the initial state for all webhooks. When you successfully enable your webhook (next), Smartsheet sets the status to "ENABLED".

You've created a webhook that subscribes to the events you want. You can enable it next.

Note: If you haven't created an event-handling endpoint at the webhook's callbackUrl that you specified, create that endpoint and return here to enable your webhook.

Enable your webhook

Enabling a Smartsheet webhook initiates the verification challenge process for it and, on successful completion of that process, the webhook starts the flow of notification events to your endpoint.

To enable your webhook, call the PUT /webhooks operation endpoint (see Update webhook for details) however you like, making sure to specify these things:

  • Webhook ID
  • Required headers
  • Request body that sets enabled to true.

For example, here's how you can update your webhook from your command line using cURL:

curl https://api.smartsheet.com/2.0/webhooks/{webhookId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-H "Content-Type: application/json" \
-X PUT \
-d '{ "enabled": true }

Smartsheet sends a verification request to your endpoint (that is, to the callbackUrl that you specified in your POST /webhooks request). On your endpoint successfully responding to the verification request, Smartsheet enables your webhook.

The response is similar to the one from creating the webhook, except it has the following encouraging result values.

  • "result.enabled": true - Smartsheet enables your webhook only after it passes the verification challenge. You initialize that process in the next section.
  • "result.status": "ENABLED"

Your webhook is enabled and sends event notifications (callbacks) to your endpoint in real time!

Note: Smartsheet periodically sends verification challenges to ensure your endpoint is listening. If your endpoint doesn't respond successfully to a verification challenge, Smartsheet disables your webhook. See Webhook verification for details.

Disabling webhooks

If you need to deactivate your webhook, call the Update webhook operation with enabled set to false.

Additional resources

Webhook callbacks

Webhook access

Previous page
Next page