# List webhooks

Gets the list of all webhooks that the user owns (if a user-generated
token was used to make the request) or the list of all webhooks associated
with the third-party app (if a third-party app made the request). Items in
the response are ordered by API creation date (most recent first).

Note: In the response, each webhook's events field defaults to "."], regardless of its actual value. Alternatively, call [GET /webhook/{webhookId} on an individual webhook to get its events value.

Endpoint: GET /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"

## Query parameters:

  - `page` (number)
    Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned.

  - `pageSize` (number)
    The maximum number of items to return per page. Unless otherwise stated for a
specific endpoint, defaults to 100. If only page is specified, defaults to a
page size of 100. For reports, the default is 100 rows. If you need larger
sets of data from your report, returns a maximum of 10,000 rows per request.

## Response 200 fields (application/json):

  - `pageNumber` (number)
    The current page.

Note: when a page number greater than total number of pages is requested, the last
page is instead returned.
    Example: 1

  - `pageSize` (number,null)
    The number of items in the current page.
    Example: 50

  - `totalPages` (integer)
    Example: -1

  - `totalCount` (integer)
    Example: -1

  - `data` (array) — one of:
    list of Webhooks
    - 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: "*.*", "user.seatType.updated", "user.seatType.*", "user.*"
      - `scope` (string)
        The type of object (that is, plan) whose events this webhook is subscribed to.
        Enum: "plan"
      - `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: "sheet"
      - `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.