Airtable Webhooks Skill

When to Use This Skill

• Setting up Airtable webhook handlers
• How do I verify the X-Airtable-Content-MAC signature?
• Why is my Airtable webhook signature verification failing?
• How do I fetch the actual changes after an Airtable notification?
• Handling base changes: tableData, tableFields, tableMetadata with add/remove/update

The Thin-Ping Model (Read This First)

Airtable webhooks are a two-step, thin-ping design and do not follow the Standard Webhooks spec:

1. Notification POST — Airtable POSTs a tiny body to your notificationUrl containing only which base/webhook changed and a timestamp. No change data.

   { "base": { "id": "appABC" }, "webhook": { "id": "achXYZ" }, "timestamp": "2022-02-01T21:25:05.663Z" }
   

   You must respond 200 or 204 with an empty body within 25 seconds.

2. Fetch payloads — To get the actual changes, call GET /v0/bases/{baseId}/webhooks/{webhookId}/payloads with a persisted cursor (a monotonically increasing transaction number). The response returns payloads, the next cursor, and mightHaveMore (loop while true; max limit is 50).

Verification (core)

Airtable signs the raw notification body with HMAC-SHA256, keyed on the base64-decoded macSecretBase64 returned once at webhook creation. The digest is hex and the header value is prefixed with hmac-sha256=.

Node:

const crypto = require('crypto');

function verify(rawBody, macHeader, macSecretBase64) {
  if (!macHeader) return false;
  const key = Buffer.from(macSecretBase64, 'base64');
  const expected = 'hmac-sha256=' + crypto.createHmac('sha256', key).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(macHeader), Buffer.from(expected));
  } catch {
    return false; // length mismatch = invalid
  }
}

Python:

import hmac, hashlib, base64

def verify(raw_body: bytes, mac_header: str, mac_secret_base64: str) -> bool:
    if not mac_header:
        return False
    key = base64.b64decode(mac_secret_base64)
    expected = "hmac-sha256=" + hmac.new(key, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac_header, expected)

For complete handlers with route wiring, payload fetching, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/

Webhook Specification (What You Subscribe To)

Airtable has no fixed event-name catalog. You create a webhook with a specification that filters which changes trigger notifications:

Each fetched payload reports changes as created / changed / destroyed records and fields per table, keyed by table id.

Environment Variables

AIRTABLE_MAC_SECRET_BASE64=your_mac_secret   # macSecretBase64 from webhook creation (returned ONCE)
AIRTABLE_PERSONAL_ACCESS_TOKEN=pat_xxx       # PAT to call the payloads API (data.records:read + webhook scopes)

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 airtable --path /webhooks/airtable

Gotchas

• PAT/OAuth webhooks expire after 7 days — refresh them (or list payloads) to extend.
• Payloads are deleted server-side after 7 days regardless of refresh.
• Failed pings retry up to 13 times with exponential backoff (~1 day), then the webhook's notifications are disabled and must be re-enabled.
• Rate limit: the webhook API shares the base's 5 requests/second limit (429 → back off ~30s).
• The official airtable npm package covers records only — call the Webhooks API directly. The community pyairtable package supports webhook CRUD, payloads, and notification validation.

Reference Materials

• references/overview.md - Airtable webhook concepts, change types
• references/setup.md - Creating a webhook, getting the MAC secret
• references/verification.md - Signature verification details and gotchas