Airtable Webhooks API Beta Deprecation Notice

Airtable is moving the Webhooks API out of beta and into general availability (GA). This document describes the changes between Airtable’s beta and GA Webhook API. You can find documentation for the updated Webhooks API here.

Changes from the webhook beta

The endpoints and general architecture of webhooks will remain the same. However, in order to better support additional API features, we made the following changes covered below:

• Webhook specification
• Payload format
• Changes to the management API

Webhook specification

The specification format has been changed. The scope field has been removed and the filters and includes parameters have been added to options. The following describes how to translate a beta specification to a GA specification.

{ 
	"scope": "tableRecords", 
	"options": { 
		"id": "tblXXX", 
		"watchFields": ["fldYYY", ...] or "all", 
		"reportFields": ["fldYYY", ...] or "all", 
		"recordTransitionTypes": ["add", "remove", "none"] or "all"
	}
}

{
	"options": {
		"filters": { 
			"dataTypes": ["tableData"], 
			"recordChangeScope": "tblXXX", 
			"watchDataInFieldIds": ["fldYYY", ...], 
			"changeTypes": ["add", "remove", "update"]
		}, 
		"includes": { 
			"includeCellValuesInFieldIds": ["fldYYY", ...] or "all"
		}
	}
}

{
	"scope": "viewRecords", 
	"options": { 
		"id": "viwXXX", 
		"watchFields": ["fldYYY", ...] or "all", 
		"reportFields": ["fldYYY", ...] or "all", 
		"recordTransitionTypes": ["add", "remove", "none"] or "all"
	}
}

{
	"options": { 
		"filters": { 
			"dataTypes": ["tableData"], 
			"recordChangeScope": "viwXXX", 
			"watchDataInFieldIds": ["fldYYY", ...], 
			"changeTypes": ["add", "remove", "update"]
		}, 
		"includes": {
			"includeCellValuesInFieldIds": ["fldYYY", ...] or "all"
		}
	}
}

{
	"scope": "base", 
	"options": {}
}

{
	"options": {
		"filters": {
			"dataTypes": ["tableData", "tableFields"]
		}, 
		"includes": {
			"includeCellValuesInFieldIds": "all"
		}
	}
}

Here are a few more notes about the changes we've made to the Webhooks specification:

• Fields may no longer be specified by name and must be specified by ID in the specification.
• In order to specify that a webhook is watching all fields for changes, omit the watchDataInFieldIds field. Similarly, changeTypes may be excluded to specify all transition types.
• In addition, we’ve added more keys to the filters and includes definitions that may be used to:
  • Filter based on what action triggered a table, record, or field to change. This may be done with fromSources.
  • Options on whether previous cell values or field definitions should be included in the payloads
  • Inclusion of table metadata as part of change data

Payload format

The payload format has changed. Here are some notes on those changes:

• The user field has been replaced with an actionMetadata field.
• Add/remove/change event types will no longer be contained in a changedTablesById or changedRecordsById and differentiated by a transitionType field. Instead, the payload will have top-level keys for each change and data type (e.g. createdTablesById, destroyedRecordsById, createdRecordsById, and destroyedTablesById, in addition to changedTablesById and changedRecordsById).
• The format of cell value payloads will be changed to match the Blocks/Scripting API. This means that certain field types, such as multipleSelects, will return an array of objects rather than an array of strings.
• When hook specifications become invalid, we will generate a payload that indicates this is the case so that appropriate actions can be taken. In such cases, the change hook specification will be marked invalid and any payload generation will be stopped.

Changes to the management API

All endpoints will continue to function and support both beta and GA formats until we deprecate the beta.

Response: 
{
	"webhooks": [{ 
		"id": "achYYY", 
		"specification": (same as what was passed to the create action), 
		"isHookEnabled": true, 
		"notificationUrl": (same as what was passed to the create action, or null if none was given), 
		"cursorForNextPayload": 1, 
		"lastNotificationResult": (result object) or null, 
		"lastSuccessfulNotificationTime": null, 
		"areNotificationsEnabled": true
	},
	... (any additional webhooks)]
}

Beta deprecation notice

Given the breaking nature of these changes, Airtable will gradually wind down support for the beta specification and payload format in two phases:

1. May 26th, 2022: We will stop allowing the creation of new beta-style webhook subscriptions.
2. August 25th, 2022: All existing beta-style webhook subscriptions will stop functioning. You will no longer receive notification pings and you will not be able to retrieve payloads.

You can migrate your existing webhooks with the following steps:

• Update your webhook handlers to support the new payload format
• Use the "List webhooks" endpoint to get all existing webhooks in a base
• Convert all specifications to the new format
• Delete each beta-style hook and register a new hook with the GA specification

If no action is taken, then any existing integrations using the beta style format at deprecation time will cease to function.