Web API

Press shift + S to search API reference.

Webhooks

Create a webhook

posthttps://api.airtable.com/v0/bases/{baseId}/webhooks

Creates a new webhook in the specified base. Payloads may be generated and the notification URL (if given) will get a ping shortly after this completes.

The number of webhooks per base is limited to 10. A single OAuth integration can create up to 2 webhooks per base.

Each webhook created with OAuth or personal access token will expire and be disabled after 7 days. The webhook life can be extended while it is still active by calling refresh webhook or list webhook payloads. After a webhook has expired and been disabled, the webhook's metadata and past payloads can be accessed for an additional 7 days.

Creator level permissions are required in order to register a webhook.

Requirements

AuthenticationPersonal access token, OAuth integration
Scope

Scopes depend on the subscribed dataTypes, more details here

User role

Base creator

Billing plansAll plans

Path parameters

baseId
string

Request body

notificationUrl
optional<string>

An optional url that can receive notification pings. See notification delivery.

specification
object

A JSON object that describe the types of changes the webhook is interested in.

options
Webhooks specification

Response format

id
string

An identifier for the webhook (WebhookId).

macSecretBase64
string

A MAC secret. The client should store this value to authenticate webhook pings. There is no way to retrieve this value after the initial creation of the webhook.

expirationTime
optional<string>

The time when the webhook expires and is disabled in the ISO format. The webhook will not expire if this is null (in the case User API keys are used)

Request (example)
Copy
$
curl -X POST "https://api.airtable.com/v0/bases/{baseId}/webhooks" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"notificationUrl": "https://foo.com/receive-ping",
"specification": {
"options": {
"filters": {
"dataTypes": [
"tableData"
],
"recordChangeScope": "tbltp8DGLhqbUmjK1"
}
}
}
}'
200 – Response (example)
{
"expirationTime": "2023-01-20T00:00:00.000Z",
"id": "ach00000000000000",
"macSecretBase64": "someBase64MacSecret"
}