# 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.

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.
        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.