用途:实现 Evernote Webhook 通知,用于实时检测变更。Webhook 只通知端点发生了变更,实际变更数据需通过同步 API 获取。
主要能力:接收 Webhook POST 请求(Evernote 以查询参数发送 userId、guid、reason);处理 create、update、notebook 三种 reason;按用户存储上次同步 USN,调用 getSyncState() 获取当前服务器 USN,再用 getFilteredSyncChunk() 拉取自上次同步以来的变更;将同步块条目路由到 onNoteCreated、onNoteUpdated、onNoteDeleted、onNotebookChanged 等处理器;通过跟踪已处理 USN 实现幂等,处理重复投递;为不支持 Webhook 的环境提供轮询回退(如每 5 分钟轮询 getSyncState(),updateCount 变化时同步)。
使用方式:创建 Express 端点接收 Webhook,立即返回 HTTP 200 后异步处理。示例:app.post('/evernote/webhook', (req, res) => { const { userId, guid, reason } = req.query; res.sendStatus(200); processWebhook({ userId, notebookGuid: guid, reason }).catch(err => console.error('Webhook processing failed:', err)); }); 同步示例:const syncState = await noteStore.getSyncState(); const chunk = await noteStore.getFilteredSyncChunk(lastUSN, 100, new Evernote.NoteStore.SyncChunkFilter({ includeNotes: true, includeNotebooks: true, includeTags: true }));
适用场景:实时笔记同步(收到更新 Webhook 后拉取同步块、更新本地数据库并经 WebSocket 通知客户端);防火墙后环境的轮询同步。
限制与前置条件:需具备 webhook 权限的 Evernote API 密钥、可被公网访问的 HTTPS 端点、了解 Evernote 同步 API。常见问题:Webhook 未收到(端点不可达)、重复 Webhook(需按 USN 幂等)、变更缺失(Webhook 与同步竞态,可延迟后重同步)、同步超时(减小 maxEntries 并分页)。性能优化见 evernote-performance-tuning。