SuperAPI AI 工具集

airtable-webhooks

编程与开发

查看项目

更新于 10-15 22:14

技能介绍

用途:帮助开发者搭建 Airtable Webhook 处理器,验证 X-Airtable-Content-MAC 签名,并在收到通知后拉取实际变更数据。

主要能力:Airtable Webhook 采用两步 thin-ping 模型,不符合 Standard Webhooks 规范。第一步,Airtable 向 notificationUrl POST 一个仅含 base、webhook 与 timestamp 的极小请求体,不含变更数据,需在 25 秒内返回 200 或 204 空响应体。第二步,调用 GET /v0/bases/{baseId}/webhooks/{webhookId}/payloads 并携带持久化 cursor(单调递增的事务号)获取真实变更,响应含 payloads、next cursor 与 mightHaveMore(为 true 时循环,单次上限 50)。

签名验证:Airtable 用 HMAC-SHA256 对原始通知体签名,密钥为创建 Webhook 时一次性返回的 macSecretBase64 经 base64 解码所得;摘要为十六进制,请求头值以 hmac-sha256= 为前缀。资料给出 Node 与 Python 的验证函数示例,并建议使用恒定时间比较。

订阅规格:Airtable 无固定事件名目录,通过 specification 过滤触发通知的变更,字段包括 dataTypes(tableData、tableFields、tableMetadata)、changeTypes(add、remove、update)、fromSources(client、publicApi、formSubmission、automation、system、sync、anonymousUser、unknown)与 recordChangeScope(限定某张表的 tableId)。拉取的 payload 按表 id 报告 created / changed / destroyed 记录与字段。

使用方式:需配置环境变量 AIRTABLE_MAC_SECRET_BASE64 与 AIRTABLE_PERSONAL_ACCESS_TOKEN(PAT 需 data.records:read 及 webhook 相关权限)。本地开发可用 npx hookdeck-cli listen 3000 airtable --path /webhooks/airtable 启动隧道。完整处理器、路由接线、payload 拉取与测试见 examples/express/、examples/nextjs/、examples/fastapi/。

限制与注意事项:PAT/OAuth Webhook 7 天后过期,需刷新或列出 payload 以延长;payload 无论是否刷新,服务端 7 天后删除;失败的 ping 最多重试 13 次并指数退避(约 1 天),之后通知被禁用需重新启用;Webhook API 与 base 共享每秒 5 次请求限制,遇 429 应退避约 30 秒;官方 airtable npm 包仅覆盖记录,需直接调用 Webhooks API,社区 pyairtable 支持 Webhook CRUD、payload 与通知验证。建议配合 webhook-handler-patterns 技能处理处理顺序、幂等(用 payload 的 baseTransactionNumber)、错误处理与重试逻辑。