Web API

Press shift + S to search API reference.

Object

Webhooks specification

Endpoints that reference this object:

object

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.

filters
object

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
optional<string>

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

dataTypes
array of ("tableData" | "tableFields" | "tableMetadata")

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
optional<array of ("add" | "remove" | "update")>

Only generate payloads that contain changes of these types.

fromSources
optional<array of ("client" | "publicApi" | "formSubmission" | "formPageSubmission" | "automation" | "system" | "sync" | "anonymousUser" | "unknown")>

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
optional<object>

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
optional<object>
pageId
string
formSubmission
optional<object>
viewId
string
watchDataInFieldIds
optional<array of strings>

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.

watchSchemasOfFieldIds
optional<array of strings>

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.

includes
optional<object>

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
optional<array of strings | "all">

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

includePreviousCellValues
optional<boolean>

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

includePreviousFieldDefinitions
optional<boolean>

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