2.0 Feature Focus: WebHooks

We’re getting ready to publicly roll out v2.0 of Context.IO and we couldn’t be more excited. In the coming weeks we’ll be rolling out a series of  posts that will take a close look at some of the new features that will be a part of 2.0. These features take Context.IO, and leveraging email data in applications, to a whole new level. One of the features we’re most excited about is the integration of WebHooks within the API.

What are WebHooks and what do they mean for Context.IO?

According to WebHooks.org, a WebHook is “an HTTP callback:… a simple event-notification via HTTP POST.”

What this means for the Context.IO API is that your app can now get notifications based on email-specific criteria such as the message recipient(s), sender, subject, whether or not a file is attached, revisions on a specific file. or even if an email is marked as “important” by Gmail, given a label, or gets placed in a particular folder. So, no more constant, resource-intensive polling to check for specific actions – WebHooks will simply notify your app whenever a desired action takes place.

What are some use cases for WebHooks in Context.IO?

Context.IO is already the API of choice to facilitate displaying the contents of a mailbox within an application. Integrating WebHooks means that applications that are only looking at email to help manage specific actions can now leverage the simplicity of Context.IO without constant polling. Here are a few sample use cases that can really benefit from WebHooks in Context.IO:

Receipt Tracking Applications

Apps that help you track travel itineraries, expenses or purchases by forwarding email receipts to a specified email address (usually receipts@appinquestion.com). These apps can leverage Context.IO by creating a WebHook that sends a notification to their application whenever a receipt enters their user’s mailbox. Applications can then integrate this receipt within their application, all without the end-user needing to take any specific action (such as forwarding).

File Storing Applications

Many of us depend on cloud-based file storage applications. Services like these can benefit from Context.IO by creating a WebHook that notifies their application whenever a user receives an email that contains an attachment. The file-storage service can then choose to pull this attachment from Context.IO into their application, so the end user’s attachments are stored seamlessly into their file-storage app of their choice.

Collaboration/Project Management Tools

Most task requests start in email and are then manually entered into a collaboration/project management tool before they can be tracked and viewed by an organization. Once the task email has been received, but prior to the task’s manual entry into a collaboration tool, task requests are often labeled as such or placed in a specific folder within the mailbox. Context.IO allows developers to create a WebHook that signals to an application that an email has been placed in a specific folder or been assigned a specific label. The collaboration tool can then pull the task thread directly into their application, and even follow the thread as it evolves, without the need for any extra steps from the end user.

Creating WebHooks

You can assign multiple WebHooks to a single account, one WebHook to multiple accounts, or, simply, one WebHook on an individual account. Required parameters are the URL that Context.IO calls when a matching message is found (callback_url) and a URL Context.IO can call should the WebHook fail (failure_notif_url). There are also a number of optional parameters that will filter the messages that you want by specific criteria (as noted above), such as the “to” field (filter_to), “from” field (filter_from) the subject line (filter_subject), and more. You can even create a WebHook that notifies your app when Gmail labels a message as “Important” (filter_new_important). And of course, we have attachment specific WebHooks that will let your application know when a file has been attached to a message (filter_file_name) or if any revisions have been made to a specific file (filter_file_revisions)

For a list of all parameters, see our documentation: http://context.io/docs/2.0/accounts/webhooks#post.

Sync Periods

The sync_period parameter is used to determine how frequently your app will check the user’s mailbox for matching items.

Basic accounts are set to check once every 24 hours by default (fine for free users or use cases such as receipt-tracking that don’t anticipate frequent matching messages). Pro accounts can set the delay to notify the application immediately upon any matching messages, or once every 1, 4, 12 or 24 hours.

To get more frequent updates on Basic accounts, you can trigger syncs (see http://context.io/docs/2.0/accounts/sync) whenever you need. Keep in mind these calls are metered at 1 cent for every 2 syncs.


These are just some of  the use cases and  ways WebHooks can make your application’s user experience that much better. Contextualizing your app with specific, meaningful data from email will make your users happy, which means they’ll use your app more and tell others to do the same. We can’t wait to see what creative things you’ll do with WebHooks.

Want to start playing with WebHooks before 2.0 is officially live? Contact SJ at sarah-jane @ context.io for preview access!

Stay tuned for our next 2.0 feature focus later this week, where we’ll be talking about our brand spankin’ new “Connect My Mailbox” button that you can use in any of your public-facing applications that should be leveraging the power of email data. This feature makes oAuth integration a walk in the park!