# Webhooks specification

A single webhook may watch changes in a table, view, or base. The specification defines the types of
the changes that are included in the webhook's payloads.

Note that tables, fields, and views in the specification must be specified by ID rather than by name.
You may find the IDs for each of these with the manage fields UI.

## Endpoints that reference this object

- [Create a webhook](https://airtable.com/developers/web/api/create-a-webhook.md)
- [List webhooks](https://airtable.com/developers/web/api/list-webhooks.md)

- `filters: object` — required

  A webhook specification can contain a filters object. For example, the specification for a webhook
  watching the data in a table is as follows:
  ```
  {
    "options": {
      "filters": {
        "dataTypes": [
          "tableData"
        ],
        "recordChangeScope": "tbl00000000000000"
      }
    }
  }
  ```
  The table events can be filtered down even more to cover just record data changes for certain fields
  from specific sources.
  ```
  {
    "options": {
      "filters": {
        "fromSources": [
          "client"
        ],
        "dataTypes": [
          "tableData"
        ],
        "recordChangeScope": "tbl00000000000000",
        "watchDataInFieldIds": [
          "fld00000000000000",
          "fld00000000000001",
          "fld00000000000002"
        ]
      }
    }
  }
  ```

  Aside from dataTypes, the keys in a filters object are optional. By default, a webhook will generate
  payloads across an entire base according to the specified dataTypes. We strongly recommend that your
  integration specify a filters object with a subset of the filter keys to ensure that your integration
  is notified for only the most relevant events.

  - `recordChangeScope: string` — optional

    Only generate payloads for changes in the specified TableId or ViewId.

    `Warning`: [Form view](https://support.airtable.com/v1/docs/form-view) and [List view](https://support.airtable.com/v1/docs/list-view) are currently not supported.

  - `dataTypes: array<"tableData" | "tableFields" | "tableMetadata">` — required

    Only generate payloads that contain changes affecting objects of these types.

    - `tableData`: record and cell value changes
    - `tableFields`: field changes
    - `tableMetadata`: table name and description changes

  - `changeTypes: array<"add" | "remove" | "update">` — optional

    Only generate payloads that contain changes of these types.

  - `fromSources: array<"client" | "publicApi" | "formSubmission" | "formPageSubmission" | "automation" | "system" | "sync" | "anonymousUser" | "unknown">` — optional

    Only generate payloads for changes from these sources.
    If omitted, changes from all sources are reported.

     - `client`: changes generated by a user through the web or mobile clients
     - `publicApi`: changes generated through the Airtable API
     - `formSubmission`: changes generated when a form _view_ is submitted
     - `formPageSubmission`: changes generated when an _interface_ form builder page, form layout page, or record creation button page is submitted
     - `automation`: changes generated through an automation action
     - `system`: changes generated by system events, such as processing time function formulas
     - `sync`: changes generated through Airtable Sync

  - `sourceOptions: object` — optional

    Additional options for source filtering.
    This allows users to filter form _view_ submissions by `ViewId`, or _interface_
    form builder page, form layout page, or record creation button page submissions by `PageId`.

    - `formPageSubmission: object` — optional

      - `pageId: string` — optional

    - `formSubmission: object` — optional

      - `viewId: string` — optional

  - `watchDataInFieldIds: array<string>` — optional

    Only generate payloads for changes that modify values in cells in these fields.
    If omitted, all fields within the table/view/base are watched.

    `Warning`: If fields are specified and one of the specified fields are deleted, the webhook
    will generate an error payload and the webhook will go into an error state and payloads will
    no longer be generated. More information about the error reponse is available in
    [Webhooks payload](https://airtable.com/developers/web/api/model/webhooks-payload.md).

  - `watchSchemasOfFieldIds: array<string>` — optional

    Only generate payloads for changes that modify the schemas of these fields.
    If omitted, schemas of all fields within the table/view/base are watched.

    `Warning`: If fields are specified and one of the specified fields are deleted, the webhook
    will generate an error payload and the webhook will go into an error state and payloads will
    no longer be generated. More information about the error reponse is available in
    [Webhooks payload](https://airtable.com/developers/web/api/model/webhooks-payload.md).

- `includes: object` — optional

  By default, the payloads only contain the data that changed. In order to generate payloads with more
  contextual data, an includes object may be added to the specification:
  ```
  {
    "options": {
      "filters": {
        "fromSources": [
          "client"
        ],
        "dataTypes": [
          "tableData"
        ],
        "recordChangeScope": "tbl00000000000000",
        "watchDataInFieldIds": [
          "fld00000000000001",
          "fld00000000000002"
        ]
      },
      "includes": {
        "includeCellValuesInFieldIds": [
          "fld00000000000000"
        ]
      }
    }
  }
  ```

  - `includeCellValuesInFieldIds: array<string> | "all"` — optional

    A list of fields to include in the payload
    regardless of whether or not they changed.

  - `includePreviousCellValues: boolean` — optional

    If true, include the previous cell value in the payload.

  - `includePreviousFieldDefinitions: boolean` — optional

    If true, include the previous field definition in the payload.