Airtable webhook expired after 7 days: refresh it, then batch Sume

An Airtable webhook created with a personal access token or OAuth token is disabled after 7 days unless you refresh it, and Airtable disables it after 13 failed ping attempts. If your base-to-video automation went quiet on day eight, that is the first thing to check. The fix is a scheduled refresh, and then one Sume bulk run per batch of changed rows.

Why did my Airtable webhook stop firing?

Airtable's webhooks overview states that webhooks created with personal access tokens or OAuth access tokens expire and are disabled after 7 days. Calling the refresh endpoint, or the list-payloads endpoint, extends the lifespan by another 7 days from that moment. After a webhook has been disabled, its metadata and past payloads stay readable for an additional 7 days.

A second cause is delivery failure. Airtable says that if a ping still does not succeed after 13 tries, it drops the ping and disables notifications for the webhook. So an outage on your receiver can end your automation just as surely as an expiry.

Is the ping the data?

No. The POST Airtable sends to your URL contains the base ID, the webhook ID and a timestamp, nothing about the rows. You then call the list-payloads endpoint to learn what changed. A hash of the body signed with the hook's MAC secret arrives in the X-Airtable-Content-MAC header, so verify it before you trust the ping.

Because list-payloads also extends the lifespan, a receiver that reads payloads on every ping keeps the webhook alive for as long as changes keep coming. A quiet base is the case that still expires, so schedule a refresh at least once a week.

How should changed rows reach Sume?

Collect the rows from one batch of payloads and send them as a single Sume bulk run: concurrency from 1 to 16, and 1 to 100 items, each item the same body as a normal Format run. One request replaces a loop of per-row calls and stays well inside Airtable's 5 requests per second per base for the Airtable side.

Mint a fresh Idempotency-Key for each batch, and make it deterministic for a given batch, so a retried ping that rebuilds the same batch replays the original queue instead of paying twice. Sume's bulk docs warn that replaying a spent key returns 202 with the old queue.

export async function submitBatch(batchId: string, rows: { id: string; brief: string }[]) {
  const res = await fetch("https://api.sume.com/v1/formats/acme/promo/bulk-runs", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SUME_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `airtable-${batchId}`,
    },
    body: JSON.stringify({
      concurrency: 3,
      items: rows.slice(0, 100).map((r) => ({
        instruction: r.brief,
        generation_spend_cap_usd: 5,
        communication: { webhook_url: "https://example.com/hooks/sume" },
      })),
    }),
  });
  if (!res.ok) throw new Error(`sume ${res.status}`);
  return (await res.json()).data.id as string; // frq_...
}

How do results get back into the base?

The bulk queue itself has no webhook. Each item can carry its own communication.webhook_url, as in the sample, and Sume sends one signed format.run.terminal POST per child when it completes or fails. Map the run back to the row yourself, for example by keeping the queue's item order next to your row IDs.

Treat outcome as the field to branch on: ok, degraded or error. Then write the media URL into the record. The run webhooks page lists the payload and the 1 MiB inline limit.

What does Sume not do?

Sume does not create, refresh or monitor your Airtable webhooks, and it has no Airtable integration in these docs. The refresh job is yours. A weekly job that refreshes every webhook and logs the new expiry is cheap insurance, and a daily one is cheaper than a missed week of orders.