Easily set webhooks for all your users
We’re introducing a new feature on Context.IO that allows developers to set webhooks at the application level, meaning you can set one webhook for your whole userbase, and we take care of the rest.
Currently, if you need to monitor certain folders for your users, you have to set a webhook for each one of your users. Another way to look at this is — webhooks are set at the user level.
So, for example, if you wanted to monitor a user’s Inbox and Sent folders, each one of your users would need to have 2 webhooks: 1 webhook set on “Inbox”, and another one set on “Sent”. This model can be difficult to manage the larger your user base gets. For 50,000 users, that means 100,000 individual webhooks to manage.
One webhook to rule them all
With application level webhooks, you do not have to POST a new webhook for each new user you acquire. If you set application level webhooks on your userbase, each new user you get will automatically be monitored under that application webhook.
This is how it works—
For user level webhooks, each user you have needs to have a webhook set on their account.
With application level webhooks, one webhook rule applies to your entire user base.
When to leverage application level webhooks
Application level webhooks are best for handling cases that will apply to all — or most — of your userbase. For example, 99% of mailboxes have an INBOX (if not all).
If your application would need to set webhooks for each user to monitor the INBOX folder, then this is a great use case for userbase webhooks.
Simply POST to “lite/webhooks” or “2.0/webhooks” with “filter_folder_added=INBOX” and this will add an application level webhook that will monitor the INBOX folder for your entire userbase!
With application level webhooks, you cannot set a different callback url for each user. You will need to use one callback url for all your users and parse the data on your end.
The webhook response for userbase callbacks includes account / user id data, so it should be fairly easy for you to route the callbacks to the appropriate user.
Here are some sample callbacks for application level webhooks in Lite and 2.0 (they are essentially the same as user level callbacks).
Some developers need to have a different callback url for each user. If this is your use case, then userbase webhooks are likely not a fit for your use case.
Modifying a webhook
If you ever need to modify an existing application level webhook, you can easily do so via a POST request to “lite/webhooks/:id” or “2.0/webhooks/:id”. This makes it easy to make changes to existing application level webhooks when a small tweak is required.
Say you were monitoring emails from a retailer for orders received, and you had a webhook set to trigger on the subject line “your order was received”. If the retailer changes the emails they are sending out to users to “we received your order”, you can easily modify your existing application level webhook by doing a POST to the webhook id as shown above.
Handling edge cases
It is likely you may run into an edge case that can’t be covered by application level webhooks.
Some developers have a use case that requires them to monitor a user’s Sent folder.
Most Sent folders are “Sent” or “\Sent”, but some are “Sent Items” or “INBOX.Sent”.
You could still user application level webhooks to monitor “Sent” or “\Sent”, which will likely catch 90% of your users. You could then set user level webhooks on edge cases for users whose Sent folder is “Sent Items” or “INBOX.Sent”.
We recommend you leverage application level webhooks for use cases that will work for the majority of your user base, and choose user level webhooks when the use case is specific to a subset of your customer accounts.