Watching for changes (Polling notifications)

Watching for Changes

Be notified of note updates by either polling or receiving HTTP notifications

Polling

If your app wants to know about changes in a user's Evernote account, you'll probably consider calling the NoteStore.findNotesMetadata function periodically to search for new notes. findNotes is incredibly powerful, but it's also expensive for our servers - we need to load the user's Lucene index, perform the search across all of their notes, hit the database to pull out the results, and send those results over the network to your app. If you're building a web application, you should use webhooks instead of polling. If you have to poll, you should follow the guidelines below.

First, don't poll more than once every 15 minutes. We keep track of calls to findNotes, and if we notice that your app is polling more frequently, we'll have to temporarily revoke your API key.

Each Evernote account has a variable named updateCount that makes it easy for you to tell whether the account has been changed since the last time you looked. Before your application searches for new notes, call NoteStore.getSyncState to check the updateCount and see if the account has changed. Here's a basic example of how that would work:

int latestUpdateCount = ... // Persist this value

// Each time you want to check for new and updated notes...
SyncState currentState = noteStore.getSyncState();
int currentUpdateCount = currentState.getUpdateCount();

if (currentUpdateCount > latestUpdateCount) {

  // Something in the account has changed, so search for notes
  NotesMetadataList newNotes = noteStore.findNotesMetadata( ... );
  
  // Do something with the notes you found...
  for (NoteMetadata note : newNotes.getNotes()) {
    // ...
  }
  
  // Keep track of the new high-water mark
  latestUpdateCount = currentSyncState.getUpdateCount();
}

Webhooks

If you're building a web service, you don't need to poll for changes. Instead, you can register to receive notifications when a user creates or updates a note. These notifications are delivered in real-time, so your application reduces latency and improves efficiency compared to polling. Notifications are sent for all users who have an unexpired OAuth session with your web service API key.

Notifications are sent as HTTP GET requests. When you register for notifications, you provide us with the URL that you'd like notifications sent to. The full HTTP request includes the numeric user ID of the Evernote user who created or updated the note, the GUID of the note, and the the reason that you're being notified:

http[s]://[your base URL][? |&]userId=[evernoteUserId]&guid=[noteGuid]&reason=[create | update]

If your service only cares about some notes, we can configure a filter on your API key. Notifications will only be sent when the note matches the filter. For example, the filter resource:image/* causes notifications to be sent anytime a note containing at least one image attachment is created or updated. The filter is configured on your API key, so it is the same for all users. The filter string supports our full search grammar.

To register for webhooks, please reach out to devsupport@evernote.com and send us the following information: your API consumer key, the URL that you would like notifications sent to, and the optional filter you wish to use.