用途:在 Knack 后端与 Vercel 仪表盘之间模拟实时更新,让 HTI 运营数据在不持续轮询的情况下实现近乎实时的同步。
主要能力:
- poll_updates:按固定间隔检查数据变化,支持 object_key、interval_seconds(默认60)、last_check_timestamp、on_change 回调,仅拉取指定时间后修改的记录。
- register_webhook:配置 Knack 在记录事件(record_created、record_updated、record_deleted)发生时向 Vercel 端点推送更新,支持共享密钥校验。
- detect_changes:识别自上次同步以来发生变化的记录,可指定 fields_to_watch 并对比缓存状态,仅返回真实变更。
使用方式: 在 Knack Builder 中进入 Settings → API & Code → Webhooks 手动创建 Webhook,设置触发条件、目标对象与 Vercel API 路由 URL。Vercel 端按 /api/knack-webhook.js 等路由接收并处理。环境变量包括 KNACK_WEBHOOK_SECRET、KNACK_APP_ID、KNACK_API_KEY。可用 curl 模拟 Webhook 进行本地测试。轮询可配合智能频率调整与 Delta Sync 优化性能。
适用场景:设备状态变更、培训课程报名、捐赠通知、状态变更工作流、仪表盘实时刷新、拨款合规进度跟踪等。
限制:Knack 无原生 WebSocket,实时性依赖轮询间隔与 Webhook 触发;Knack API 限制为每秒10次请求,建议关键更新用 Webhook、非紧急数据用轮询;错误处理需应对 429 限流与 5xx 服务端错误,采用退避重试。