- 26 Sep 2023
- 3 Minutes to read
- Print
- DarkLight
Airtable Webhooks API Beta Deprecation Notice
- Updated on 26 Sep 2023
- 3 Minutes to read
- Print
- DarkLight
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.
The information in this article is only relevant to those users who were part of our beta Webhook API testing group.
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
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.
Beta specification | GA specification |
|
|
Beta specification | GA specification |
|
|
Beta specification | GA specification |
|
|
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
andincludes
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
- Filter based on what action triggered a table, record, or field to change. This may be done with
Payload format
The payload format has changed. Here are some notes on those changes:
- The
user
field has been replaced with anactionMetadata
field. - Add/remove/change event types will no longer be contained in a
changedTablesById
orchangedRecordsById
and differentiated by atransitionType
field. Instead, the payload will have top-level keys for each change and data type (e.g.createdTablesById
,destroyedRecordsById
,createdRecordsById
, anddestroyedTablesById
, in addition tochangedTablesById
andchangedRecordsById
). - 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)]
}
Specifically,
perChangeHookTransactionNumberForNextPayload
has been renamed to cursorForNextPayload
and isHookEnabled
has been added.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:
- May 26th, 2022: We will stop allowing the creation of new beta-style webhook subscriptions.
- 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.