Using Webhooks with the Yodlee API

Overview

Webhooks HTTP callbacks that can be used as notifications that an event of interest has occurred. Client applications can subscribe to these events and then can act appropriately when the notification is received.

Envestnet | Yodlee provides webhooks support for two events:

1. REFRESH
2. DATA_UPDATES

Let’s understand how each one works in detail:

1. Refresh— In addition to using FastLink to link users' accounts to the aggregation platform, Envestnet | Yodlee customers can link their users' accounts directly through the API. Historically, developers would need to poll continuously to know the status of the account linking process. With webhooks, the Envestnet | Yodlee platform will keep client applications informed about the event without the need for continuous polling.

For account linking, client applications can use webhooks to know:

• what MFA (multi-factor authentication) information is being requested by the provider site to log in
• whether the Yodlee system has logged in to the provider site successfully or not
• whether the Yodlee system successfully retrieved the account summary information from the provider site
• the final status of adding or updating accounts through the API

2. Data Updates— After accounts are added/linked with the aggregation platform, Yodlee keeps their data up to date by running a nightly cache refresh on behalf of the user. Envestnet | Yodlee manages the cache refresh process to uniformly distribute the load throughout the course of a day within a specified refresh window. Customers can use webhooks to receive data update notifications that are triggered when any of their users’ accounts are refreshed/updated. After receiving a notification the client application can extract the delta—the updated information for the consumer’s accounts and transactions.

For data updates, client applications can use webhooks to receive the following data update notifications:

• A successful or failed action to add a provider account through APIs or Yodlee FastLink.
• Status on a successful or failed action to update/refresh a provider account through APIs, Yodlee FastLink, or through the application.
• Deleting a provider account through APIs or the application.
• Updates to the details of an aggregated account or a manual account through APIs or the application.
• Adding a manual account using APIs or Yodlee FastLink.
• Deleting an aggregated account or a manual account using APIs or the application.
• Updating an aggregated transaction through APIs or the application (for example, updating the transaction category).
• Cache/auto refreshes

APIs for Webhooks

Customers can use the following webhook services under the /cobrand/config/notifications/events end point:

• event subscription – Subscribing to an event
• update subscription – Updating the callback URL
• get event subscriptions – Retrieving subscribed events
• remove subscription – Unsubscribing from an event

Setting up Webhooks

Customers can set up webhooks by subscribing to an event for which they want notifications. This is a one-time activity for an API environment and applies to all users.

Steps for subscribing/unsubscribing to an event:

1. Create a cobSession token using POST /cobrand/login
2. Once, you have a cobSession token, you can subscribe to one or both events individually. In order to subscribe to the REFRESH or DATA_UPDATES events, use POST /cobrand/config/notifications/events/{eventName}. The callback URL (where Yodlee should send the notification) is specified in the body of the request.
3. If you want to update the callback URL, you can use PUT /cobrand/config/notifications/events/{eventName}. The callback URL is specified in the body of the request.
4. If you want to stop receiving notifications, you can unsubscribe to the events using DELETE /cobrand/config/notifications/events/{eventName}.
5. You can also determine which events you have subscribed to by using GET /cobrand/config/notifications/events/{eventName}.

Best Practices

• Customers should ensure that they whitelist (if needed) the Envestnet | Yodlee IP addresses from which the notifications are sent. Please contact sales to determine the relevant IP addresses.
• Customers should ensure that the callback URL has the default port (HTTPS–443, HTTP–80).
• Customers should not poll for status using GET /providerAccounts{providerAccountId}; if you do, you may not receive the notification.
• Note that subscribing to events is a one-time activity for the client application, and is not done on a per user basis. The subscription applies to all users of the client application.

FAQs

1. Is webhook support available for the legacy SOAP and REST APIs?
   No. Webhook support is available only for the new RESTful Yodlee APIs.
 
2. Are Yodlee webhooks the same as alerts?
   No. Yodlee webhooks are not alerts. Webhooks are notifications sent to customers and not to users. Customers are expected to take actions as needed.