--- title: "Create webhook" method: POST path: "/webhooks" tags: ["webhooks"] --- # Create webhook `POST /webhooks` Creates a new Webhook. > **Important:** On creation, a webhook is inactive by default. You can activate the webhook by calling the [Update webhook](/api/smartsheet/openapi/webhooks/updatewebhook) 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](/api/smartsheet/guides/webhooks/launch-a-plan-level-webhook) > - [Create a plan event-handling endpoint](/api/smartsheet/guides/users/automate-user-seat-type-management/create-an-endpoint-to-handle-user-seat-type-events) article > **Note:** For sheet webhooks, you can now filter which events trigger callbacks by specifying event patterns in the `events` array (for example, `["row.created", "cell.updated"]`). If you omit specific patterns or use `["*.*"]`, the webhook receives all event types. See the [`events`](/api/smartsheet/openapi/schemas/sheetwebhook) property for supported patterns. ## Headers - `Content-Type` string ## Request body - union - object - `callbackUrl` string, required — HTTPS URL where callbacks are sent. - `name` string, required — Webhook name. - `id` number — ID of the webhook. - `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. - `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. - `createdAt` union - string, date-time - number - `disabledDetails` string — Details about the reason the webhook was disabled. It's only present when enabled=false. - `modifiedAt` union - string, date-time - number - `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. - `stats` object - `lastCallbackAttempt` string, date-time — When this webhook last made a callback attempt. - `lastCallbackAttemptRetryCount` number — The number of retries the webhook had performed as of the last callback attempt. - `lastSuccessfulCallback` string, date-time — When this webhook last made a successful callback. - `events` string[], 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). - `scope` 'plan', required — The type of object (that is, `plan`) whose events this webhook is subscribed to. - `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. - `status` 'DISABLED_ADMINISTRATIVE' | 'DISABLED_APP_REVOKED' | 'DISABLED_BY_OWNER' | 'DISABLED_CALLBACK_FAILED' | 'DISABLED_SCOPE_INACCESSIBLE' | 'DISABLED_VERIFICATION_FAILED' | 'ENABLED' | 'NEW_NOT_VERIFIED' — The webhook's status. See [Webhook Status](/api/smartsheet/guides/webhooks/webhook-status) for details. - `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. - `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 - object - `callbackUrl` string, required — HTTPS URL where callbacks are sent. - `name` string, required — Webhook name. - `id` number — ID of the webhook. - `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. - `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. - `createdAt` union - string, date-time - number - `disabledDetails` string — Details about the reason the webhook was disabled. It's only present when enabled=false. - `modifiedAt` union - string, date-time - number - `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. - `stats` object - `lastCallbackAttempt` string, date-time — When this webhook last made a callback attempt. - `lastCallbackAttemptRetryCount` number — The number of retries the webhook had performed as of the last callback attempt. - `lastSuccessfulCallback` string, date-time — When this webhook last made a successful callback. - `events` string[], required — Array of patterns for matching sheet event types. You can use `"*.*"` to subscribe to all event types (default), or specify one or more supported event patterns to receive only matching events: **Supported patterns:** | Pattern | Matches | |---|---| | `*.*` | All sheet event types | | `cell.*` | All cell events | | `cell.created` | Cell created | | `cell.updated` | Cell updated | | `cell.deleted` | Cell deleted | | `row.*` | All row events | | `row.created` | Row created | | `row.updated` | Row updated | | `row.deleted` | Row deleted | | `column.*` | All column events | | `column.created` | Column created | | `column.updated` | Column updated | | `column.deleted` | Column deleted | | `sheet.*` | All sheet events | | `sheet.created` | Sheet created | | `sheet.updated` | Sheet updated | | `sheet.deleted` | Sheet deleted | | `attachment.*` | All attachment events | | `attachment.created` | Attachment created | | `attachment.updated` | Attachment updated | | `attachment.deleted` | Attachment deleted | | `discussion.*` | All discussion events | | `discussion.created` | Discussion created | | `discussion.updated` | Discussion updated | | `discussion.deleted` | Discussion deleted | | `comment.*` | All comment events | | `comment.created` | Comment created | | `comment.updated` | Comment updated | | `comment.deleted` | Comment deleted | **Notes:** - You can combine multiple patterns, for example `["row.created", "cell.updated"]`. - Duplicate patterns are automatically deduplicated. - If `"*.*"` is included, it takes precedence over any other patterns. - Pattern matching is case-insensitive. - `scope` 'sheet', required — The type of object (that is, `sheet`) whose events this webhook is subscribed to. - `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**. - `status` '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' — The webhook's status. See [Webhook Status](/api/smartsheet/guides/webhooks/webhook-status) for details. - `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. - `columnIds` integer[] — Array of IDs of the sheet columns to monitor. - `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 - `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` Result object, containing a Webhook object for the newly created webhook - object - `message` 'PARTIAL_SUCCESS' | 'SUCCESS' — Message that indicates the outcome of the request. (One of `SUCCESS` or `PARTIAL_SUCCESS`.) - `resultCode` 0 | 3 — * '0' Success * '3' Partial Success of Bulk Operation - `result` union — The webhook object. - object - `callbackUrl` string — HTTPS URL where callbacks are sent. - `name` string — Webhook name. - `id` number — ID of the webhook. - `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. - `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. - `createdAt` union - string, date-time - number - `disabledDetails` string — Details about the reason the webhook was disabled. It's only present when enabled=false. - `modifiedAt` union - string, date-time - number - `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. - `stats` object - `lastCallbackAttempt` string, date-time — When this webhook last made a callback attempt. - `lastCallbackAttemptRetryCount` number — The number of retries the webhook had performed as of the last callback attempt. - `lastSuccessfulCallback` string, date-time — When this webhook last made a successful callback. - `events` string[] — Array of patterns for matching plan event types. Can contain either '\*.\*' (all events) and/or 'user.seatType.updated' (to monitor user seat type changes). - `scope` 'plan' — Scope of the subscription. - `scopeObjectId` integer — ID of the object whose events this webhook is subscribed to. - `status` 'DISABLED_ADMINISTRATIVE' | 'DISABLED_APP_REVOKED' | 'DISABLED_BY_OWNER' | 'DISABLED_CALLBACK_FAILED' | 'DISABLED_SCOPE_INACCESSIBLE' | 'DISABLED_VERIFICATION_FAILED' | 'ENABLED' | 'NEW_NOT_VERIFIED' — The webhook's status. See [Webhook Status](/api/smartsheet/guides/webhooks/webhook-status) for details. - `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. - `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 - `enabled` boolean — If `true`, the webhook is activated; Otherwise, it's inactive or deactivated. - object - `callbackUrl` string — HTTPS URL where callbacks are sent. - `name` string — Webhook name. - `id` number — ID of the webhook. - `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. - `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. - `createdAt` union - string, date-time - number - `disabledDetails` string — Details about the reason the webhook was disabled. It's only present when enabled=false. - `modifiedAt` union - string, date-time - number - `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. - `stats` object - `lastCallbackAttempt` string, date-time — When this webhook last made a callback attempt. - `lastCallbackAttemptRetryCount` number — The number of retries the webhook had performed as of the last callback attempt. - `lastSuccessfulCallback` string, date-time — When this webhook last made a successful callback. - `events` string[] — Array of patterns for matching sheet event types. You can use `"*.*"` to subscribe to all event types (default), or specify one or more supported event patterns to receive only matching events: **Supported patterns:** | Pattern | Matches | |---|---| | `*.*` | All sheet event types | | `cell.*` | All cell events | | `cell.created` | Cell created | | `cell.updated` | Cell updated | | `cell.deleted` | Cell deleted | | `row.*` | All row events | | `row.created` | Row created | | `row.updated` | Row updated | | `row.deleted` | Row deleted | | `column.*` | All column events | | `column.created` | Column created | | `column.updated` | Column updated | | `column.deleted` | Column deleted | | `sheet.*` | All sheet events | | `sheet.created` | Sheet created | | `sheet.updated` | Sheet updated | | `sheet.deleted` | Sheet deleted | | `attachment.*` | All attachment events | | `attachment.created` | Attachment created | | `attachment.updated` | Attachment updated | | `attachment.deleted` | Attachment deleted | | `discussion.*` | All discussion events | | `discussion.created` | Discussion created | | `discussion.updated` | Discussion updated | | `discussion.deleted` | Discussion deleted | | `comment.*` | All comment events | | `comment.created` | Comment created | | `comment.updated` | Comment updated | | `comment.deleted` | Comment deleted | **Notes:** - You can combine multiple patterns, for example `["row.created", "cell.updated"]`. - Duplicate patterns are automatically deduplicated. - If `"*.*"` is included, it takes precedence over any other patterns. - Pattern matching is case-insensitive. - `scope` 'sheet' — Scope of the subscription. - `scopeObjectId` integer — ID of the object whose events this webhook is subscribed to. - `status` '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' — The webhook's status. See [Webhook Status](/api/smartsheet/guides/webhooks/webhook-status) for details. - `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. - `columnIds` integer[] — Array of IDs of the sheet columns to monitor. - `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 - `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. ## Other responses - `default` — Error Payload --- [API](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference.md) · [All operations](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smartsheet/smartsheet-openapi-reference/versions/b4afda95fb51/schema)