# 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](/api/smartsheet/guides/users/automate-user-seat-type-management/create-an-endpoint-to-handle-user-seat-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

- **System Admin permissions.** You must be a System Admin to create plan-level webhooks (plan webhooks).
- **Smartsheet API access token.** You can generate an access token (key) in the Smartsheet UI.
- **Callback URL to your endpoint** for receiving and handling the events. If you haven't already created an endpoint, see [Create an endpoint for user type events](/api/smartsheet/guides/users/automate-user-seat-type-management/create-an-endpoint-to-handle-user-seat-type-events).


## Create a webhook

You can create a plan webhook by calling the [Create webhook](/api/smartsheet/openapi/webhooks/createwebhook) 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:


```bash
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,
    "customHeaders": {
      "YOUR_CUSTOM_HEADER_KEY_1": "YOUR_CUSTOM_HEADER_VALUE_1",
      "YOUR_CUSTOM_HEADER_KEY_2": "YOUR_CUSTOM_HEADER_VALUE_2",
      ...
    }
}' \
  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.
- `YOUR_CUSTOM_HEADER_KEY/VALUE`: Use this to provide any custom headers required by your endpoint.


> **Note:** To specifically filter on user seat type updates, you can replace the `events` field's `["*.*"]` value with `["user.seatType.updated"]`. We currently only support  `"user.seatType.updated"` events for plan-level webhooks.


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

Response:


```json
{
  "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](/api/smartsheet/openapi/webhooks/updatewebhook) 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:


```bash
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](/api/smartsheet/openapi/webhooks/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.


```json
{
  "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](/api/smartsheet/guides/webhooks/webhook-callbacks#authenticating-callbacks-optional).


> **Note:** If you need to deactivate your webhook, call the [Update webhook](/api/smartsheet/openapi/webhooks/updatewebhook) operation with `enabled` set to `false`.


## What's next?

Based on the event data you extracted at your [endpoint](/api/smartsheet/guides/users/automate-user-seat-type-management/create-an-endpoint-to-handle-user-seat-type-events) 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](/api/smartsheet/guides/users/automate-user-seat-type-management/execute-user-upgrades-and-downgrades) next.