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:

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:

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.