Skip to content
HookDeploy

Airtable webhooks

Last verified against Airtable's documentation on September 27, 2026.

On this page ↓

Airtable webhooks tell you that something changed in a base: a record was created, a cell was updated, a field was renamed. Unlike most webhooks, they don’t tell you what changed. The notification is a thin ping, and you fetch the changes yourself from a separate endpoint. Add a 7-day expiry, a MAC secret you only see once, and notifications that switch themselves off after a day of failures, and Airtable webhooks trip up a lot of developers. This page covers what Airtable sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Airtable sends webhooks for

You create an Airtable webhook through the API with a specification describing what to watch. The main filter is dataTypes:

Data typeWhat it watchesTypical use
tableDataRecords created, updated, or deletedSync records to a database, CRM, or search index
tableFieldsFields created, changed, or deletedKeep a downstream schema in step with the base
tableMetadataTable names and descriptionsTrack structural changes to a base

Two more filters narrow things down: recordChangeScope limits a webhook to one table or view, and fromSources filters by where a change came from, for example to ignore changes your own automation made.

The notification itself is always the same small JSON body, no matter what changed:

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

To see the changes, your handler calls GET /v0/bases/{baseId}/webhooks/{webhookId}/payloads with a cursor. Each payload carries a transaction number that increases in sequence, and the response tells you whether more pages are waiting.

How Airtable delivers webhooks

BehaviorDetail
Notification bodyBase ID, webhook ID, and a timestamp. No change data
Signature headerX-Airtable-Content-MAC, formatted hmac-sha256=<hex>: an HMAC-SHA256 of the body, keyed with the base64-decoded MAC secret
MAC secretReturned as macSecretBase64 when you create the webhook
Timestamp in signatureNone. The MAC doesn’t expire
Expected response200 or 204, with an empty body
Timeout25 seconds to connect, send, and receive the response
RetriesUp to 13 times with exponential backoff starting at 10 seconds, covering roughly a day
After 13 failuresThe ping is dropped and notifications are disabled for that webhook. Payloads keep being generated
ExpiryWebhooks created with a personal access token or OAuth token expire after 7 days. Refreshing the webhook or listing its payloads extends it 7 days from that moment
Payload retention7 days. After a webhook expires, its metadata and past payloads stay readable for another 7 days
Delivery guaranteeAt least once. Pings can be spurious (no new changes) or coalesced (one ping for several changes)
OrderingPings aren’t ordered. Payloads from the payloads endpoint are
Limits10 webhooks per base. An OAuth integration can create 2 per base
Rate limit5 requests per second per base, shared with the REST API. A 429 means waiting 30 seconds

Common Airtable webhook errors and how to fix them

Webhook stopped firing after a week

Webhooks created with a personal access token or OAuth token expire after 7 days. Call the refresh endpoint, POST /v0/bases/{baseId}/webhooks/{webhookId}/refresh, or list the webhook’s payloads, before the expiry to push it out another 7 days. If it already expired, create a new one. The old webhook’s payloads stay readable for 7 more days, so you can still catch up.

Notifications disabled

If a ping fails 13 times over about a day, Airtable drops it and turns off notifications for the webhook. Fix your endpoint, then re-enable them with the enable or disable webhook notifications endpoint. Payloads kept being generated the whole time, so fetch from your last cursor to catch up on everything you missed.

The ping has no data

That’s by design. The notification only says which webhook fired. Call the payloads endpoint with your stored cursor, process every payload returned, save the new cursor, and keep paging while the response says more might be available.

MAC verification fails

  • The secret isn’t decoded. macSecretBase64 is base64. Decode it before using it as the HMAC key.
  • Missing prefix. The header value is hmac-sha256= followed by the hex digest. Compare the whole string.
  • The body changed. Verify against the raw request body rather than a re-serialized object.
  • The secret was lost. You get macSecretBase64 when the webhook is created. If you didn’t store it, delete the webhook and create a new one.

429 errors from the payloads endpoint

The payloads endpoint shares the base’s 5 requests per second limit with the rest of the API. When a burst of pings arrives, don’t fetch once per ping. Since one fetch returns everything since your cursor, collapse a burst of pings into a single catch-up fetch.

Duplicate or empty pings

Pings are at least once, and some arrive when nothing new has happened. Your handler shouldn’t assume a ping means new data. Fetch from your cursor, and if nothing comes back, there’s nothing to do.

Webhook limit reached

A base allows 10 webhooks, and an OAuth integration can create only 2 per base. If several systems need Airtable changes, one webhook with fan-out is the way around the limit.

Why use HookDeploy with Airtable

Keep notifications switched on

Airtable disables a webhook’s notifications after a day of failed pings, and from then on changes pile up silently until someone notices. HookDeploy captures each ping at Cloudflare’s edge and responds to Airtable right away, before forwarding it to your server, so downtime on your side doesn’t count as a failed ping. From there:

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.

Every ping keeps the webhook alive

Listing a webhook’s payloads extends its 7-day expiry. When HookDeploy delivers each ping and your handler fetches payloads in response, an active webhook renews itself. Only a base that goes a full week without changes needs a scheduled refresh from your own system.

Replays are safe by design

Because Airtable pings carry no data, retrying or replaying one can’t deliver stale changes. It just prompts your handler to fetch from its cursor. And because the MAC has no timestamp, a replayed ping verifies no matter how old it is.

One webhook, many consumers

Airtable caps webhooks at 10 per base, and OAuth integrations at 2. Point one webhook at HookDeploy and forward each ping to every system that needs to know about changes. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Sync to systems Airtable can’t reach

Airtable needs a public URL for notifications. The HookDeploy Agent connects outward from your network over mTLS and delivers pings to a local port, so an internal database or sync worker can follow a base without exposing a public endpoint. The worker still needs outbound access to Airtable’s API to fetch payloads.

Know the limits

  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Airtable counts as a failed ping. Paid plans keep accepting traffic past the included volume.
  • Transformations and privacy filters. A transformation changes the body, and a privacy filter changes the stored copy used for retries and replays. Either way, the MAC won’t match at that destination.

Retries, replays, and duplicates

Airtable already sends duplicate and spurious pings, so your handler has to tolerate them. That same design makes HookDeploy’s retries and replays harmless: every extra ping just triggers a fetch from your cursor.

The rule that keeps it all correct: your cursor is the source of truth, not the ping. Store the cursor durably after each successful fetch, and use each payload’s transaction number to skip anything you’ve already processed. A ping that arrives late, twice, or after a replay changes nothing.

Set up Airtable with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Airtable sync) and copy its URL.
  2. Create the webhook with Airtable’s API, using a token with the webhook:manage and data.records:read scopes. Save the id and macSecretBase64 from the response, since you can’t get the secret again:
curl -X POST "https://api.airtable.com/v0/bases/YOUR_BASE_ID/webhooks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationUrl": "https://hookdeploy.dev/h/YOUR_SLUG",
    "specification": {
      "options": {
        "filters": {
          "dataTypes": ["tableData"],
          "recordChangeScope": "YOUR_TABLE_ID"
        }
      }
    }
  }'
  1. In HookDeploy, add a forward destination pointing to your handler, or to an agent for private delivery, and set its retries.
  2. If the base can go a week without changes, schedule a daily POST to https://api.airtable.com/v0/bases/YOUR_BASE_ID/webhooks/YOUR_WEBHOOK_ID/refresh from your own system, with your token in the Authorization header.
  3. Edit a record in the watched table, and confirm the ping appears in HookDeploy and your handler fetches the change.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const macKey = Buffer.from(process.env.AIRTABLE_MAC_SECRET_BASE64, 'base64');

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/airtable', express.raw({ type: 'application/json' }), async (req, res) => {
  const received = req.get('x-airtable-content-mac') ?? '';
  const expected = 'hmac-sha256=' + crypto
    .createHmac('sha256', macKey)
    .update(req.body)   // raw bytes, untouched
    .digest('hex');

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send('Invalid MAC');

  res.sendStatus(204);
  const { base, webhook } = JSON.parse(req.body.toString('utf8'));
  await enqueueCatchUp(base.id, webhook.id);  // one fetch covers a burst of pings
});

// In your worker: fetch everything since the stored cursor.
async function catchUp(baseId, webhookId) {
  let cursor = await loadCursor(webhookId);
  let more = true;
  while (more) {
    const url = `https://api.airtable.com/v0/bases/${baseId}/webhooks/${webhookId}/payloads?cursor=${cursor}`;
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AIRTABLE_TOKEN}` } });
    const page = await res.json();
    for (const payload of page.payloads) await applyChange(payload);
    cursor = page.cursor;
    more = page.mightHaveMore;
    await saveCursor(webhookId, cursor);
  }
}

FAQ

Why doesn't the Airtable webhook include the changed data?

Airtable's notification is a ping, not a payload. It tells you which base and webhook changed, and your handler then calls the list webhook payloads endpoint with a cursor to fetch the actual changes. One ping can stand for several changes.

Why did my Airtable webhook stop working after a week?

Webhooks created with a personal access token or OAuth token expire after 7 days. Refreshing the webhook or listing its payloads extends it by another 7 days, so a handler that fetches payloads after each ping keeps an active webhook alive on its own. For bases that can go a week without changes, call the refresh endpoint on a schedule.

Does HookDeploy break Airtable's MAC verification?

No. HookDeploy forwards Airtable's original body and X-Airtable-Content-MAC header unchanged. The MAC has no timestamp, so retries and replays verify too. Verification fails only if a transformation changes the body, or a privacy filter changed the stored copy used for retries and replays.

Will HookDeploy stop Airtable from disabling my notifications?

Yes, as long as HookDeploy captures the ping. Airtable disables notifications after a ping fails 13 times over about a day, and HookDeploy responds to Airtable right away even when your server is down. Requests HookDeploy rejects before capture, such as those over a Free plan's limits, still count as failures.

Does Airtable need an empty response body?

Airtable asks for a 200 or 204 with an empty body, but it judges failures by status code, connection, and timing. HookDeploy's default 200 response works. On Starter and above, you can set a custom response of 204 with an empty body to match Airtable's request exactly.

Should I use an Airtable automation instead?

If you only need to send record data somewhere when something happens, Airtable itself suggests an automation with a Run a script action may be simpler, and that script can post to a HookDeploy endpoint. The Webhooks API is better for syncing or replicating changes across a whole table or base.

Capture Airtable webhooks free

Start free