evernote-webhooks-events

name	evernote-webhooks-events
description	Implement Evernote webhook notifications and sync events. Use when handling note changes, implementing real-time sync, or processing Evernote notifications. Trigger with phrases like "evernote webhook", "evernote events", "evernote sync", "evernote notifications".
allowed-tools	Read, Write, Edit, Bash(curl:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Evernote Webhooks & Events

Overview

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

Prerequisites

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

How Evernote Webhooks Work

Unlike most APIs, Evernote webhooks only notify that a user's account changed. They do NOT include the actual changes in the payload. You must:

1. Receive webhook notification
2. Use sync API to fetch actual changes
3. Process the retrieved changes

Instructions

Step 1: Webhook Endpoint

// routes/webhooks.js
const express = require('express');
const crypto = require('crypto');
const router = express.Router();

// Evernote webhook endpoint
router.get('/webhooks/evernote', (req, res) => {
  // Evernote sends GET requests for webhooks
  const {
    userId,      // Evernote user ID
    guid,        // GUID of changed note (if applicable)
    notebookGuid,// GUID of changed notebook (if applicable)
    reason       // Reason for notification
  } = req.query;

  console.log('Webhook received:', {
    userId,
    guid,
    notebookGuid,
    reason,
    timestamp: new Date().toISOString()
  });

  // Acknowledge receipt immediately
  res.status(200).send('OK');

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

async function processWebhook(userId, guid, notebookGuid, reason) {
  
   syncQueue.(, {
    userId,
    guid,
    notebookGuid,
    reason,
    : .()
  });
}

. = router;

Step 2: Webhook Reasons

// Evernote webhook reasons
const WebhookReasons = {
  CREATE: 'create',    // New note created
  UPDATE: 'update',    // Note updated
  // Note: No DELETE reason - must detect via sync
};

// Handle different webhook types
async function handleWebhookByReason(userId, guid, reason) {
  switch (reason) {
    case WebhookReasons.CREATE:
      await handleNoteCreated(userId, guid);
      break;

    case WebhookReasons.UPDATE:
      await handleNoteUpdated(userId, guid);
      break;

    default:
      // Unknown reason - perform full sync check
      await performIncrementalSync(userId);
  }
}

Step 3: Sync State Management

// services/sync-service.js
const Evernote = require('evernote');

class SyncService {
  constructor(noteStore) {
    this.noteStore = noteStore;
    this.lastUpdateCount = 0;
  }

  /**
   * Get current sync state
   */
  async getSyncState() {
    return this.noteStore.getSyncState();
  }

  /**
   * Check if sync is needed
   */
  async needsSync(lastKnownUpdateCount) {
    const state = await this.getSyncState();
    return state.updateCount > lastKnownUpdateCount;
  }

  /**
   * Perform incremental sync
   */
  async incrementalSync(afterUpdateCount) {
    const chunks = [];
    let currentUpdateCount = afterUpdateCount;

    while (true) {
      // Get sync chunk
      const chunk = await this.noteStore.getFilteredSyncChunk(
        currentUpdateCount,
        100, 
        {
          : ,
          : ,
          : ,
          :   
        }
      );

      chunks.(chunk);

      
       (chunk. >= chunk.) {
        ;
      }

      currentUpdateCount = chunk.;
    }

     .(chunks);
  }

  
  () {
     changes = {
      : { : [], : [], : [] },
      : { : [], : [], : [] },
      : { : [], : [], : [] }
    };

     ( chunk  chunks) {
      
       (chunk.) {
         ( note  chunk.) {
           (note.) {
            changes...(note.);
          }   (note. === note.) {
            changes...(note);
          }  {
            changes...(note);
          }
        }
      }

      
       (chunk.) {
        changes...(...chunk.);
      }

      
       (chunk.) {
         ( notebook  chunk.) {
          changes...(notebook);
        }
      }

       (chunk.) {
        changes...(...chunk.);
      }

      
       (chunk.) {
         ( tag  chunk.) {
          changes...(tag);
        }
      }

       (chunk.) {
        changes...(...chunk.);
      }
    }

     changes;
  }
}

. = ;

Step 4: Webhook Event Processing

// services/event-processor.js
const EventEmitter = require('events');

class EvernoteEventProcessor extends EventEmitter {
  constructor(syncService, options = {}) {
    super();
    this.syncService = syncService;
    this.processingLock = new Map();
    this.debounceMs = options.debounceMs || 5000;
    this.pendingWebhooks = new Map();
  }

  /**
   * Handle incoming webhook (debounced)
   */
  async handleWebhook(userId, guid, reason) {
    const key = `${userId}`;

    // Debounce multiple webhooks for same user
    if (this.pendingWebhooks.has(key)) {
      clearTimeout(this.pendingWebhooks.get(key));
    }

    this.pendingWebhooks.set(key, setTimeout(async () => {
      this..(key);
       .(userId);
    }, .));
  }

  
   () {
    
     (..(userId)) {
      .();
      ;
    }

    ..(userId, );

     {
      
       lastUpdateCount =  .(userId);

      
       (! ..(lastUpdateCount)) {
        .();
        ;
      }

      
       changes =  ..(lastUpdateCount);

      
      .(userId, changes);

      
       state =  ..();
       .(userId, state.);

    }  {
      ..(userId);
    }
  }

  
  () {
    
     ( note  changes..) {
      .(, { userId, note });
    }

     ( note  changes..) {
      .(, { userId, note });
    }

     ( guid  changes..) {
      .(, { userId, guid });
    }

    
     ( notebook  changes..) {
      .(, { userId, notebook });
    }

     ( guid  changes..) {
      .(, { userId, guid });
    }

    
     ( tag  changes..) {
      .(, { userId, tag });
    }

     ( guid  changes..) {
      .(, { userId, guid });
    }

    
    .(, {
      userId,
      : {
        : changes...,
        : changes...,
        : changes...
      }
    });
  }

  
   () {
    
     ; 
  }

   () {
    
  }
}

. = ;

Step 5: Event Handlers

// handlers/event-handlers.js
const processor = require('./event-processor');

// Handle new notes
processor.on('note:created', async ({ userId, note }) => {
  console.log(`New note created: ${note.title}`);

  // Example: Index for search
  await searchIndex.indexNote(note);

  // Example: Send notification
  await notifications.send(userId, {
    type: 'note_created',
    title: note.title
  });
});

// Handle note updates
processor.on('note:updated', async ({ userId, note }) => {
  console.log(`Note updated: ${note.title}`);

  // Example: Update search index
  await searchIndex.updateNote(note);

  // Example: Sync to external service
  await externalSync.updateNote(userId, note);
});

// Handle note deletions
processor.on('note:deleted', async ({ userId, guid }) => {
  console.log(`Note deleted: ${guid}`);

  // Example: Remove from search index
  await searchIndex.(guid);

  
   database.(guid);
});


processor.(,  {
  .(, summary);

  
  metrics.({
    userId,
    ...summary
  });
});

Step 6: Webhook Registration

// Note: Webhook registration is done through Evernote Developer Portal
// API key settings, not through the API itself.

// Webhook configuration in Evernote Developer Portal:
// 1. Go to https://dev.evernote.com/
// 2. Navigate to your API key settings
// 3. Enable webhooks
// 4. Set webhook URL: https://your-domain.com/webhooks/evernote

// For local development, use ngrok:
// ngrok http 3000
// Then update webhook URL temporarily in developer portal

Step 7: Polling Fallback

// services/polling-service.js

/**
 * Fallback polling for when webhooks aren't available
 * or as a backup sync mechanism
 */
class PollingService {
  constructor(syncService, options = {}) {
    this.syncService = syncService;
    this.pollInterval = options.pollInterval || 5 * 60 * 1000; // 5 minutes
    this.users = new Map(); // userId -> lastUpdateCount
    this.timer = null;
  }

  /**
   * Start polling for a user
   */
  addUser(userId, accessToken) {
    this.users.set(userId, {
      accessToken,
      lastUpdateCount: 0
    });
  }

  /**
   * Remove user from polling
   */
  removeUser(userId) {
    this.users.delete(userId);
  }

  /**
   * Start polling loop
   */
  start() {
    if (this.timer) return;

    this.timer = setInterval( () => {
       .();
    }, .);

    .();
  }

  
  () {
     (.) {
      (.);
      . = ;
    }
  }

  
   () {
     ( [userId, data]  .) {
       {
         .(userId, data);
      }  (error) {
        .(, error.);
      }
    }
  }

  
   () {
     state =  ..();

     (state. > data.) {
      .();

       changes =  ..(
        data.
      );

      
      data. = state.;

      
       .(userId, changes);
    }
  }

   () {
    
  }
}

. = ;

Output

• Webhook endpoint implementation
• Sync state management
• Event-driven change processing
• Event handlers for note lifecycle
• Polling fallback mechanism

Webhook vs Polling

Aspect	Webhooks	Polling
Latency	Near real-time	Poll interval
Rate limit impact	None	Uses API quota
Reliability	Depends on network	Consistent
Setup complexity	Requires public URL	Simple
Recommended	Production	Development/backup

Error Handling

Issue	Cause	Solution
Webhook not received	URL not reachable	Verify HTTPS endpoint
Duplicate webhooks	Network retries	Implement idempotency
Missing changes	Race condition	Re-sync after timeout
Sync timeout	Large change set	Increase chunk size

Resources

• Webhooks Overview
• Synchronization
• Developer Portal

Next Steps

For performance optimization, see evernote-performance-tuning.