Web API

Press shift + S to search API reference.

Webhooks

List webhook payloads

gethttps://api.airtable.com/v0/bases/{baseId}/webhooks/{webhookId}/payloads

Enumerate the update messages for a client to consume. Clients should call this after they receive a ping.

The webhook payload format can be found here and uses V2 cell value format.

Calling this endpoint will also extend the life of the webhook if it is active with an expiration time. The new expiration time will be 7 days after the list payloads call.

Requirements

AuthenticationPersonal access token, OAuth integration
Scope

Scopes depend on the subscribed dataTypes, more details here

User role

Base read-only

Billing plansAll plans

Path parameters

baseId
string
webhookId
string

Query parameters

cursor
optional<number>

The first time this action is called, the cursor argument may be omitted from the request and will default to 1. After that, cursors should be saved between invocations of this action. When a client receives a ping, it should use the last cursor that this action returned when polling for new payloads, no matter how old that cursor value is. The cursor argument indicates the transaction number of the payload to start listing from.

limit
optional<number>

If given the limit parameter specifies the maximum number of payloads to return in the response. A maximum of 50 payloads can be returned in a single request. A single payload can contain multiple updates.

Response format

cursor
number

The cursor field in the response indicates the transaction number of the payload that would immediately follow the last payload returned in this request. Payloads are returned in transaction order, so the last payload's transaction number is (cursor-1), the second-to-last payload's transaction number is (cursor-2), and so on. Each payload is associated with an incrementing cursor number. If there are no returned payloads, then the cursor in the response will be the same as the cursor specified in the request. The number of the next payload to be generated can be retrieved from cursorForNextPayload in list webhooks. Payloads are deleted from Airtable's servers after 1 week whether or not the client has seen them. The cursor value for the next payload is never reset, even if payloads are deleted.

mightHaveMore
boolean

Indicates whether or not there are additional payloads. If mightHaveMore is true, the client should send another request immediately and pass in the cursor from this response, as there could be more payloads. If mightHaveMore is false, there are definitely no more payloads.

payloads
array of Webhooks payloads
Request (example)
Copy
$
curl "https://api.airtable.com/v0/bases/{baseId}/webhooks/{webhookId}/payloads" \
-H "Authorization: Bearer YOUR_TOKEN"
200 – Response (example)
{
"cursor": 5,
"mightHaveMore": false,
"payloads": [
{
"actionMetadata": {
"source": "client",
"sourceMetadata": {
"user": {
"email": "foo@bar.com",
"id": "usr00000000000000",
"permissionLevel": "create"
}
}
},
"baseTransactionNumber": 4,
"payloadFormat": "v0",
"timestamp": "2022-02-01T21:25:05.663Z"
}
]
}