evernote-webhooks-events

Evernote Webhooks & Events

Overview

Implement Evernote webhook notifications for real-time change detection. Evernote webhooks notify your endpoint that changes occurred, but you must use the sync API to retrieve the actual changed data.

Prerequisites

• Evernote API key with webhook permissions
• HTTPS endpoint accessible from the internet
• Understanding of Evernote sync API

Instructions

Step 1: Webhook Endpoint

Create an Express endpoint that receives webhook POST requests. Evernote sends userId, guid (notebook GUID), and reason (create, update, notebook) as query parameters. Respond with HTTP 200 immediately, then process asynchronously.

app.post('/evernote/webhook', (req, res) => {
  const { userId, guid, reason } = req.query;
  res.sendStatus(200); // Respond immediately

  // Process asynchronously
  processWebhook({ userId, notebookGuid: guid, reason })
    .catch(err => console.error('Webhook processing failed:', err));
});

Step 2: Webhook Reasons

Handle three webhook reasons: create (new note created), update (note modified), and notebook (notebook-level change). Each triggers a sync of the affected notebook.

Step 3: Sync State Management

Store the last sync USN per user. On webhook receipt, call getSyncState() to get the current server USN, then getFilteredSyncChunk() to fetch only the changes since your last sync.

const syncState = await noteStore.getSyncState();
const chunk = await noteStore.getFilteredSyncChunk(
  lastUSN,
  100,  // maxEntries
  new Evernote.NoteStore.SyncChunkFilter({
    includeNotes: true,
    includeNotebooks: true,
    includeTags: true
  })
);

Step 4: Event Processing and Handlers

Route sync chunk entries to typed handlers: onNoteCreated, onNoteUpdated, onNoteDeleted, onNotebookChanged. Implement idempotency by tracking processed USNs to handle duplicate webhook deliveries.

Step 5: Polling Fallback

Implement a polling fallback for environments where webhooks are unavailable. Poll getSyncState() on a timer (e.g., every 5 minutes) and sync when updateCount changes.

For the full webhook server, sync manager, event handlers, and polling implementations, see Implementation Guide.

Output

• Express webhook endpoint with async processing
• Sync state manager with USN tracking
• Event router for create, update, and delete operations
• Idempotent event processing (handles duplicate deliveries)
• Polling fallback for non-webhook environments

Error Handling

Issue	Cause	Solution
Webhook not received	URL not reachable from Evernote servers	Verify HTTPS endpoint is publicly accessible
Duplicate webhooks	Network retries by Evernote	Track processed USNs for idempotency
Missing changes	Race condition between webhook and sync	Re-sync with small delay after webhook
Sync timeout	Large change set in chunk	Reduce maxEntries per chunk, paginate

Resources

• Webhooks Overview
• Synchronization
• Developer Portal

Next Steps

For performance optimization, see evernote-performance-tuning.

Examples

Real-time note sync: Receive webhook on note update, fetch the sync chunk, update local database, and notify connected clients via WebSocket.

Polling-based sync: For environments behind firewalls, poll getSyncState() every 5 minutes and process any changes via the same handler pipeline used by webhooks.