# Airtable Webhooks

## 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.
  
  
  ```json
  { "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:

```javascript
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:

```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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/airtable-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/airtable-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/airtable-webhooks/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:

| Field | Values |
| --- | --- |
| `dataTypes` | `tableData`, `tableFields`, `tableMetadata` |
| `changeTypes` | `add`, `remove`, `update` |
| `fromSources` | `client`, `publicApi`, `formSubmission`, `automation`, `system`, `sync`, `anonymousUser`, `unknown` |
| `recordChangeScope` | a `tableId` to scope record changes to one table |

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

## Environment Variables

```bash
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

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/airtable-webhooks/references/overview.md) - Airtable webhook concepts, change types
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/airtable-webhooks/references/setup.md) - Creating a webhook, getting the MAC secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/airtable-webhooks/references/verification.md) - Signature verification details and gotchas