Guides
/
Users
/
Automate user seat type management
/
Launch a plan-level webhook
Last updated

Launch a plan-level webhook

A plan-scoped Smartsheet webhook subscribes you to receive user plan type notifications at an endpoint location you specify (for example, the URL of the endpoint you created in Create an endpoint for user type events).

This tutorial demonstrates how to create a Smartsheet webhook and enable it to start receiving plan-scoped, user seat type event notifications.

Prerequisites

Create a webhook

You can create a plan-level webhook by calling the Create webhook operation (that is, POST /webhooks) with scope set to plan.

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

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "smartsheet-integration-source: APPLICATION,YOUR_ORGANIZATION,YOUR_APP_NAME" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "YOUR_ENDPOINT_URL",
    "events": [
      "*.*"
    ],
    "name": "YOUR_WEBHOOK_NAME",
    "scope": "plan",
    "scopeObjectId": YOUR_PLAN_ID,
    "version": 1
}' \
  https://api.smartsheet.com/2.0/webhooks

Replace the following placeholder values with your own values.

  • YOUR_TOKEN_HERE: Your API access token (key).
  • YOUR_ORGANIZATION: Name of your company or organization.
  • YOUR_APP_NAME: Your app's name.
  • YOUR_ENDPOINT_URL: Your endpoint's location.
  • YOUR_WEBHOOK_NAME: Arbitrary name for your webhook.
  • YOUR_PLAN_ID: Your plan's ID number. You can access your plan ID in Admin Center by clicking on your profile icon in the top-right corner. See the Admin Center Overview for details.

After calling the POST /webhooks operation, your new webhook exists, and you get a response like the one below.

Response:

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "id": 9876543210,
    "scopeObjectId": YOUR_PLAN_ID,
    "name": "YOUR_WEBHOOK_NAME",
    "callbackUrl": "YOUR_ENDPOINT_URL",
    "version": 1,
    "events": [
      "*.*"
    ],
    "enabled": false,
    "status": "NEW_NOT_VERIFIED",
    "sharedSecret": "abcd1234",
    "scope": "plan",
    "subscope": {
      "columnIds": []
    },
    "createdAt": "2025-08-26T18:10:12Z",
    "modifiedAt": "2025-08-26T18:10:12Z"
  }
}

Important: Record your new webhook's ID (that is, the id value). You must pass in the webhook ID in calls to update your webhook, which includes enabling your webhook.

Note, your webhook isn't yet sending events. That requires enabling the webhook.

Enable your webhook

You must call the Update webhook operation (that is, POST /webhooks/{webhookId}) with "enabled": true, to enable your webhook. Enabling your webhook initiates the Smartsheet verification challenge process for it and, on successful completion of that process, your webhook starts the flow of notification events to your endpoint.

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

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "smartsheet-integration-source: APPLICATION,YOUR_ORGANIZATION,YOUR_APP_NAME" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true 
}' \
  https://api.smartsheet.com/2.0/webhooks/{webhookId}

Replace the following placeholders with your values.

  • YOUR_TOKEN_HERE: Your API access token (key).
  • YOUR_ORGANIZATION: Name of your company or organization.
  • YOUR_APP_NAME: Your app's name.
  • {webhookId}: Your webhook's identifier. It was the id value in the response from your POST /webhooks call. Another way to find the id is to call the List webhooks operation (that is, GET /webhooks) and search the response for your webhook.

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

{
  "version": 3,
  "failedItems": [],
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "callbackUrl": "YOUR_ENDPOINT_URL",
    "events": [
      "*.*"
    ],
    "name": "YOUR_WEBHOOK_NAME",
    "scope": "plan",
    "scopeObjectId": 3456789012,
    "subscope": {},
    "version": 2,
    "enabled": false,
    "id": 9876543210,
    "createdAt": "2024-08-24T14:15:22Z",
    "disabledDetails": "",
    "modifiedAt": "2024-08-24T14:15:22Z",
    "sharedSecret": "abcd1234",
    "stats": {
      "lastCallbackAttempt": "2024-08-24T14:15:22Z",
      "lastCallbackAttemptRetryCount": 0,
      "lastSuccessfulCallback": "2024-08-24T14:15:22Z"
    },
    "status": "ENABLED"
  }
}

The response is similar to the one from creating the webhook, but there are some new webhook fields and some changed webhook field values worth noting.

These updated fields show that the webhook is enabled:

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

Note: The sharedSecret value is worth recording if you want to authenticate callbacks. For details, see Webhook callbacks.

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

What's next?

Based on the event data you extracted at your endpoint and your user seat type management logic -- this might include rules-based decision-making or workflows in ServiceNow or similar IT service managment (ITSM) environments -- you can upgrade or downgrade users to seat types you want. Go to Execute user upgrades and downgrades next.

Previous page
Next page