Watching for Changes

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


Overview

Many applications watch a user's Evernote account and take an action when a note is created or updated. Web applications can take advantage of Evernote's webhooks to receive real-time notifications of such changes. For apps where webhooks aren't appropriate, we have some tips to improve efficiency when polling for changes.

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 affected notebook, and the the reason that you're being notified. For operations relating to individuals notes, the GUID of the note will also be included in the notification.

Here are each of the possible notification formats:

// Create Notebook
[base URL]/?userId=[user ID]&notebookGuid=[notebook GUID]&reason=notebook_create
// Update Notebook
[base URL]/?userId=[user ID]&notebookGuid=[notebook GUID]&reason=notebook_update
// Create Note
[base URL]/?userId=[user ID]&guid=[note GUID]&notebookGuid=[notebook GUID]&reason=create
// Update Note
[base URL]/?userId=[user ID]&guid=[note GUID]&notebookGuid=[notebook GUID]&reason=update
// Create Business Notebook
[base URL]/?userId=[user ID]&notebookGuid=[notebook GUID]&reason=business_notebook_create
// Update Business Notebook
[base URL]/?userId=[user ID]&notebookGuid=[notebook GUID]&reason=business_notebook_update
// Create Business Note
[base URL]/?userId=[user ID]&guid=[note GUID]&notebookGuid=[notebook GUID]&reason=business_create
// Update Business Note
[base URL]/?userId=[user ID]&guid=[note GUID]&notebookGuid=[notebook GUID]&reason=business_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.

Webhooks are also available for Evernote Business. They behave slightly differently than normal webhooks:

  • Third parties will only be notified of changes made to Business data by users who have authorized the third-party's integration. In other words, if Bob has authorized your integration and Susan has not, you'll only receive notifications when Bob creates or changes a Business note.
  • Notifications sent for changes to Business data will contain business_create or business_update reason codes.
  • When you receive a notification for a new or updated Business note, retrieve the note by obtaining the a business authentication token for the specified user, then connecting to the corresponding Business NoteStore.

To register for webhooks, please open a developer support ticket 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.

Stay on top of what's happening in the Evernote developer community.
Complete the form below to open a support request with the Evernote Developer Relations team.
Important: we are ending access to the Sandbox environment from November 15, 2023. Use this form to request your Sandbox API keys to be promoted to production.

Please explain how your application
uses create, read, and update permissions.
Complete the form below to have your integration considered for inclusion in the App Center.
Complete the form below to request your complimentary 1-year Squarespace account.