# Create webhook

Creates a new Webhook.

> Important: On creation, a webhook is inactive by default. You can activate the webhook by calling the Update webhook operation on it with enabled set to true.

Webhook instance limits

Each scope object, such as a plan or a sheet, can have a maximum number of associated webhooks.

| Object | Maximum webhooks |
| :----------- | :-------------------------- |
| Plan         | 100 |
| Sheet        | 100k | 

> Note: You can pass custom headers in your webhook requests, which Smartsheet then adds to all requests that the webhook sends to your callback URL. This is useful for including authentication tokens or other information your application needs. To do this, add a customHeaders object to the request body, with each key-value pair representing a header and its value.
> 
> See also:
> 
> - customHeaders body parameter in the Body section below
> - Launch a plan-level webhook
> - Create a plan event-handling endpoint article

Endpoint: POST /webhooks
Version: 2.0.0
Security: APIToken, OAuth2

## Header parameters:

  - `Authorization` (string)
    API Access Token used to authenticate requests to Smartsheet APIs.

  - `smartsheet-integration-source` (string)
    Uses the following metadata to distinguish between human-initiated API requests and third-party service-initiated calls by AI Connectors or ITSM:

- Integration source type
- Organization name
- Integration source name 

Format:


TYPE,OrgName,SourceName


Examples: 

AI,SampleOrg,My-AI-Connector-v2

SCRIPT,SampleOrg2,Accounting-updater-script

APPLICATION,SampleOrg3,SheetUpdater
    Example: "AI,SampleOrg,My-AI-Connector-v2"

  - `Content-Type` (string)
    Required for POST and PUT requests. Defines the structure for the request body.

## Request fields (application/json):

  - `body` (Plan webhook (object) or Sheet webhook (object)) — one of:
    - Plan webhook:
      - `callbackUrl` (string, required)
        HTTPS URL where callbacks are sent.
        Example: "https://www.myApp.com/webhooks"
      - `name` (string, required)
        Webhook name.
        Example: "My webhook"
      - `events` (array, required)
        Array of patterns for matching plan event types.

Can contain either '\.\' (all events) and/or 'user.seatType.updated' (to monitor user seat type changes).
        Enum: "*.*", "user.seatType.updated", "user.seatType.*", "user.*"
      - `scope` (string, required)
        The type of object (that is, plan) whose events this webhook is subscribed to.
        Enum: "plan"
      - `scopeObjectId` (integer, required)
        ID of the plan whose events this webhook is subscribed to. After creating a webhook, this value is immutable.

Note: You can access a plan's ID in the Admin Center UI by clicking on your profile icon in the top-right corner. See the Admin Center Overview for details.
        Example: 3285357287499652
      - `version` (number, required)
        Webhook version. Currently, the only supported value is 1. This attribute is intended to ensure backward compatibility as new webhook functionality is released. For example, a webhook with a version of 1 is guaranteed to always be sent callback objects that are compatible with the version 1 release of webhooks.
        Example: 1
      - `customHeaders` (object)
        A set of custom headers that your webhook sends in all requests to your callback URL, where each key-value pair represents a header name and its corresponding value.

This can be useful for passing authentication tokens or other information that your application needs to process the webhook events. 

Important: Don't use any of the following reserved headers as custom headers:

- Accept-Encoding
- Connection
- Content-Length
- Host
- Proxy-Authenticate
- Proxy-Authorization
- Smartsheet-Change-Agent
- Smartsheet-Hmac-SHA256
- Smartsheet-Hook-Challenge
- Smartsheet-Hook-Response
- TE
- Trailer
- Transfer-Encoding
- Upgrade
- User-Agent
        Example: {"YOUR_CUSTOM_HEADER_KEY_1":"YOUR_CUSTOM_HEADER_VALUE_1","YOUR_CUSTOM_HEADER_KEY_2":"YOUR_CUSTOM_HEADER_VALUE_2"}
    - Sheet webhook:
      - `callbackUrl` (string, required)
        HTTPS URL where callbacks are sent.
        Example: "https://www.myApp.com/webhooks"
      - `name` (string, required)
        Webhook name.
        Example: "My webhook"
      - `events` (array, required)
        Array of patterns for matching sheet event types.

Important: Currently, it must contain only the string value '"\.\"' (asterisk period asterisk) as its sole element. This pattern matches all sheet event types.
        Example: ["*.*"]
      - `scope` (string, required)
        The type of object (that is, sheet) whose events this webhook is subscribed to.
        Enum: "sheet"
      - `scopeObjectId` (integer, required)
        ID of the sheet whose events this webhook is subscribed to. After creating a webhook, this value is immutable.

Note: You can access a sheet's ID in the Smartsheet UI by looking at the sheet's properties under File > Properties.
        Example: 3285357287499652
      - `subscope` (object)
        Limits the webhook to monitor specific columns designated by an array of sheet column IDs. 

Note: If a cell in one of the columns is deleted as part of a row deletion, the webhook still sends a "row.deleted" callback event.
      - `subscope.columnIds` (array)
        Array of IDs of the sheet columns to monitor.
        Example: [7318427511613316,7318427511613123]
      - `customHeaders` (object)
        A set of custom headers that your webhook sends in all requests to your callback URL, where each key-value pair represents a header name and its corresponding value.

This can be useful for passing authentication tokens or other information that your application needs to process the webhook events. 

Important: Don't use any of the following reserved headers as custom headers:

- Accept-Encoding
- Connection
- Content-Length
- Host
- Proxy-Authenticate
- Proxy-Authorization
- Smartsheet-Change-Agent
- Smartsheet-Hmac-SHA256
- Smartsheet-Hook-Challenge
- Smartsheet-Hook-Response
- TE
- Trailer
- Transfer-Encoding
- Upgrade
- User-Agent
        Example: {"YOUR_CUSTOM_HEADER_KEY_1":"YOUR_CUSTOM_HEADER_VALUE_1","YOUR_CUSTOM_HEADER_KEY_2":"YOUR_CUSTOM_HEADER_VALUE_2"}
      - `version` (number, required)
        Webhook version. Currently, the only supported value is 1. This attribute is intended to ensure backward compatibility as new webhook functionality is released. For example, a webhook with a version of 1 is guaranteed to always be sent callback objects that are compatible with the version 1 release of webhooks.

## Response 200 fields (application/json):

  - `message` (string)
    Message that indicates the outcome of the request. (One of SUCCESS or PARTIAL_SUCCESS.)
    Enum: "PARTIAL_SUCCESS", "SUCCESS"

  - `resultCode` (number)
    * '0' Success
* '3' Partial Success of Bulk Operation
    Enum: 0, 3

  - `result` (any) — one of:
    The webhook object.
    - Plan webhook:
      - `callbackUrl` (string)
        HTTPS URL where callbacks are sent.
        Example: "https://www.myApp.com/webhooks"
      - `name` (string)
        Webhook name.
        Example: "My webhook"
      - `id` (number)
        ID of the webhook.
        Example: 8444254503626628
      - `apiClientId` (string)
        ID of the corresponding third-party app that created the webhook. It's only present if the webhook was created by a third-party app.
        Example: "555555"
      - `apiClientName` (string)
        API client name corresponding to third-party app that created the webhook. It's only present if the webhook was created by a third-party app.
        Example: "Awesome Smartsheet Application"
      - `createdAt` (any)
      - `disabledDetails` (string)
        Details about the reason the webhook was disabled. It's only present when enabled=false.
      - `modifiedAt` (any)
      - `sharedSecret` (string)
        Shared secret for this webhook, randomly generated by Smartsheet.

See [Authenticating Callbacks](/api/smartsheet/guides/webhooks/webhook-callbacks#authenticating-callbacks-optional) for details about how this value can be used.
        Example: "216ejjzdnq17mq1q8xs7d4hu8b"
      - `stats` (object)
      - `stats.lastCallbackAttempt` (string)
        When this webhook last made a callback attempt.
      - `stats.lastCallbackAttemptRetryCount` (number)
        The number of retries the webhook had performed as of the last callback attempt.
      - `stats.lastSuccessfulCallback` (string)
        When this webhook last made a successful callback.
      - `events` (array)
        Array of patterns for matching plan event types.

Can contain either '\.\' (all events) and/or 'user.seatType.updated' (to monitor user seat type changes).
        Enum: same as `events` in "Plan webhook" (4 values)
      - `scope` (string)
        The type of object (that is, plan) whose events this webhook is subscribed to.
        Enum: same as `scope` in "Plan webhook" (1 values)
      - `scopeObjectId` (integer)
        ID of the plan whose events this webhook is subscribed to. After creating a webhook, this value is immutable.

Note: You can access a plan's ID in the Admin Center UI by clicking on your profile icon in the top-right corner. See the Admin Center Overview for details.
        Example: 3285357287499652
      - `status` (string)
        The webhook's status.

See [Webhook Status](/api/smartsheet/guides/webhooks/webhook-status) for details.
        Enum: "DISABLED_ADMINISTRATIVE", "DISABLED_APP_REVOKED", "DISABLED_BY_OWNER", "DISABLED_CALLBACK_FAILED", "DISABLED_SCOPE_INACCESSIBLE", "DISABLED_VERIFICATION_FAILED", "ENABLED", "NEW_NOT_VERIFIED"
      - `version` (number)
        Webhook version. Currently, the only supported value is 1. This attribute is intended to ensure backward compatibility as new webhook functionality is released. For example, a webhook with a version of 1 is guaranteed to always be sent callback objects that are compatible with the version 1 release of webhooks.
        Example: 1
      - `customHeaders` (object)
        A set of custom headers that your webhook sends in all requests to your callback URL, where each key-value pair represents a header name and its corresponding value.

This can be useful for passing authentication tokens or other information that your application needs to process the webhook events. 

Important: Don't use any of the following reserved headers as custom headers:

- Accept-Encoding
- Connection
- Content-Length
- Host
- Proxy-Authenticate
- Proxy-Authorization
- Smartsheet-Change-Agent
- Smartsheet-Hmac-SHA256
- Smartsheet-Hook-Challenge
- Smartsheet-Hook-Response
- TE
- Trailer
- Transfer-Encoding
- Upgrade
- User-Agent
        Example: {"YOUR_CUSTOM_HEADER_KEY_1":"YOUR_CUSTOM_HEADER_VALUE_1","YOUR_CUSTOM_HEADER_KEY_2":"YOUR_CUSTOM_HEADER_VALUE_2"}
      - `enabled` (boolean)
        If true, the webhook is activated; Otherwise, it's inactive or deactivated.
    - Sheet webhook:
      - `callbackUrl` (string)
        HTTPS URL where callbacks are sent.
        Example: "https://www.myApp.com/webhooks"
      - `name` (string)
        Webhook name.
        Example: "My webhook"
      - `id` (number)
        ID of the webhook.
        Example: 8444254503626628
      - `apiClientId` (string)
        ID of the corresponding third-party app that created the webhook. It's only present if the webhook was created by a third-party app.
        Example: "555555"
      - `apiClientName` (string)
        API client name corresponding to third-party app that created the webhook. It's only present if the webhook was created by a third-party app.
        Example: "Awesome Smartsheet Application"
      - `createdAt` (any)
      - `disabledDetails` (string)
        Details about the reason the webhook was disabled. It's only present when enabled=false.
      - `modifiedAt` (any)
      - `sharedSecret` (string)
        Shared secret for this webhook, randomly generated by Smartsheet.

See [Authenticating Callbacks](/api/smartsheet/guides/webhooks/webhook-callbacks#authenticating-callbacks-optional) for details about how this value can be used.
        Example: "216ejjzdnq17mq1q8xs7d4hu8b"
      - `stats` (object)
      - `stats.lastCallbackAttempt` (string)
        When this webhook last made a callback attempt.
      - `stats.lastCallbackAttemptRetryCount` (number)
        The number of retries the webhook had performed as of the last callback attempt.
      - `stats.lastSuccessfulCallback` (string)
        When this webhook last made a successful callback.
      - `events` (array)
        Array of patterns for matching sheet event types.

Important: Currently, it must contain only the string value '"\.\"' (asterisk period asterisk) as its sole element. This pattern matches all sheet event types.
        Example: ["*.*"]
      - `scope` (string)
        The type of object (that is, sheet) whose events this webhook is subscribed to.
        Enum: same as `scope` in "Sheet webhook" (1 values)
      - `scopeObjectId` (integer)
        ID of the sheet whose events this webhook is subscribed to. After creating a webhook, this value is immutable.

Note: You can access a sheet's ID in the Smartsheet UI by looking at the sheet's properties under File > Properties.
        Example: 3285357287499652
      - `status` (string)
        The webhook's status.

See [Webhook Status](/api/smartsheet/guides/webhooks/webhook-status) for details.
        Enum: "DISABLED_ADMINISTRATIVE", "DISABLED_APP_REVOKED", "DISABLED_BY_OWNER", "DISABLED_CALLBACK_FAILED", "DISABLED_EXCEEDED_GRID_LIMITS", "DISABLED_SCOPE_INACCESSIBLE", "DISABLED_VERIFICATION_FAILED", "ENABLED", "NEW_NOT_VERIFIED"
      - `subscope` (object)
        Limits the webhook to monitor specific columns designated by an array of sheet column IDs. 

Note: If a cell in one of the columns is deleted as part of a row deletion, the webhook still sends a "row.deleted" callback event.
      - `subscope.columnIds` (array)
        Array of IDs of the sheet columns to monitor.
        Example: [7318427511613316,7318427511613123]
      - `customHeaders` (object)
        A set of custom headers that your webhook sends in all requests to your callback URL, where each key-value pair represents a header name and its corresponding value.

This can be useful for passing authentication tokens or other information that your application needs to process the webhook events. 

Important: Don't use any of the following reserved headers as custom headers:

- Accept-Encoding
- Connection
- Content-Length
- Host
- Proxy-Authenticate
- Proxy-Authorization
- Smartsheet-Change-Agent
- Smartsheet-Hmac-SHA256
- Smartsheet-Hook-Challenge
- Smartsheet-Hook-Response
- TE
- Trailer
- Transfer-Encoding
- Upgrade
- User-Agent
        Example: {"YOUR_CUSTOM_HEADER_KEY_1":"YOUR_CUSTOM_HEADER_VALUE_1","YOUR_CUSTOM_HEADER_KEY_2":"YOUR_CUSTOM_HEADER_VALUE_2"}
      - `version` (number)
        Webhook version. Currently, the only supported value is 1. This attribute is intended to ensure backward compatibility as new webhook functionality is released. For example, a webhook with a version of 1 is guaranteed to always be sent callback objects that are compatible with the version 1 release of webhooks.
      - `enabled` (boolean)
        If true, the webhook is activated; Otherwise, it's inactive or deactivated.

## Response default fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.