Sorry, you need to enable JavaScript to visit this website.
Skip to main content

Refresh Webhooks

What is a REFRESH Event?

The event REFRESH refers to notifications that are sent during the stages of the add account and update account processes triggered by users.

Notifications will be sent while customers edit credentials, add, or refresh/update accounts for the latest information using Yodlee APIs. The refresh webhooks notification lets customers know:

  • The provider site has requested MFA information to log in for aggregating data.
  • The Yodlee system has successfully logged in to the provider site.
  • The Yodlee system has successfully retrieved the account summary information from the provider site.
  • The final status of account addition or update account APIs.

Types of REFRESH Event

There are three refresh-related events for which notifications will be sent to customers.

User Input Required

User Input Required events notify customers that the provider site needs some additional authentication information from the user to successfully add or update his/her account. This will be triggered for multifactor authentication (MFA) based provider sites. 

Note: There is a chance that the MFA information is provided in the add account API or update account API response. In this case, the notifications will not be sent to customers. 

Interim Progress

The two interim progress events follow:

  • Login Success: This notifies customers that the login action has successfully completed on the provider site.
  • Account Summary: This notifies customers that the account summary information has been successfully retrieved from the provider site. This event is provider site-specific and will be provided to the customer as applicable.

Process Completed

This notifies customers that the process of adding or updating an account has been completed.

Refresh Event Flow

The following diagram explains the flow between the customer, the Yodlee system, and the provider site when the customer has subscribed to notifications.

Event Payload Information

The payload sent to the customer-provided URL has a common structure, whereas the data attribute within the structure varies for every notification. The following JSON payload will be sent to the callback URL, and the content type will be application/json:

"event": {
    "info": "REFRESH.PROCESS_COMPLETED",
    "loginName": "fri21",
    "data": {
      "providerAccount": [
        {
          "id": 10995860,
          "providerId": 16441,
          "isManual": false,
          "createdDate": "2017-12-22T05:47:35Z",
          "aggregationSource": "USER",
          "status": "SUCCESS",
         "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
          "dataset": [
            {
              "name": "BASIC_AGG_DATA",
              "additionalStatus": "AVAILABLE_DATA_RETRIEVED",
              "updateEligibility": "ALLOW_UPDATE",
              "lastUpdated": "2017-12-22T05:48:16Z",
              "lastUpdateAttempt": "2017-12-22T05:48:16Z"
            }
          ]
        }
      ]
    }
  }
Events Event-Data Attribute Details

REFRESH.USER_INPUT_REQUIRED

User Input Required Event Response

MFA type - Question & Answer

{
  "event": {
    "info": "REFRESH.USER_INPUT_REQUIRED",
    "loginName": "fri21",
    "data": {
      "providerAccount": [
        {
          "id": 10995861,
          "providerId": 16442,
          "isManual": false,
          "createdDate": "2017-12-22T05:54:31Z",
          "status": "USER_INPUT_REQUIRED",
          "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
          "aggregationSource": "USER",
          "dataset": [
            {
              "name": "BASIC_AGG_DATA",
              "updateEligibility": "DISALLOW_UPDATE"
            }
          ],
          "loginForm": [
            {
              "mfaTimeout": 125000,
              "formType": "questionAndAnswer",
              "row": [
                {
                  "id": "SQandA--QUESTION_1--Row--1",
                  "label": "What is the name of your state?",
                  "fieldRowChoice": "0001",
                  "form": "0001",
                  "field": [
                    {
                      "id": "SQandA--QUESTION_1--1",
                      "name": "QUESTION_1",
                      "isOptional": false,
                      "value": "Enter the answer",
                      "valueEditable": "true",
                      "type": "text"
                    }
                  ]
                },
                {
                  "id": "SQandA--QUESTION_2--Row--2",
                  "label": "What is the name of your first school",
                  "fieldRowChoice": "0002",
                  "form": "0001",
                  "field": [
                    {
                      "id": "SQandA--QUESTION_2--2",
                      "name": "QUESTION_2",
                      "isOptional": false,
                      "value": "Enter the answer",
                      "valueEditable": "true",
                      "type": "text"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

MFA type - Token

{
  "event": {
    "info": "REFRESH.USER_INPUT_REQUIRED",
    "loginName": "fri21",
    "data": {
      "providerAccount": [
        {
          "id": 10995861,
          "providerId": 16442,
          "isManual": false,
          "createdDate": "2017-12-22T05:54:31Z",
          "status": "USER_INPUT_REQUIRED",
          "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
          "aggregationSource": "USER",
          "dataset": [
            {
              "name": "BASIC_AGG_DATA",
              "updateEligibility": "DISALLOW_UPDATE"
            }
          ],
          "loginForm": [
            {
              "mfaTimeout": 125000,
              "formType": "token",
              "row": [
                {
                  "id": "token_row",
                  "label": "Security Key",
                  "fieldRowChoice": "0001",
                  "form": "0001",
                  "field": [
                    {
                      "id": "token",
                      "name": "tokenValue",
                      "isOptional": "false",
                      "value": "",
                      "valueEditable": "true",
                      "maxLength": 10,
                      "type": "text"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

MFA type - Image

{
  "event": {
    "info": "REFRESH.USER_INPUT_REQUIRED",
    "loginName": "fri21",
    "data": {
      "providerAccount": [
        {
          "id": 10995861,
          "providerId": 16442,
          "isManual": false,
          "createdDate": "2017-12-22T05:54:31Z",
          "status" : "USER_INPUT_REQUIRED"
          "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
          "aggregationSource": "USER",
          "dataset": [
            {
              "name": "BASIC_AGG_DATA",
              "updateEligibility": "DISALLOW_UPDATE"
            }
          ],
          "loginForm": {
            "mfaTimeout": 59250,
            "formType": "image",
            "row": [
              {
                "id": "image_row",
                "fieldRowChoice": "0001",
                "form": "0001",
                "field": [
                  {
                    "id": "image",
                    "name": "imageValue",
                    "isOptional": false,
                    "value": "",
                    "valueEditable": "true",
                    "minLength": 5,
                    "maxLength": 10,
                    "type": "text",
                    "image": [
                      66,
                      77,
                      -122
                    ]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

REFRESH.INTERIM_PROGRESS

Login Success Event Response

{
  "event": {
    "info": "REFRESH.INTERIM_PROGRESS",
    "loginName": "fri21",
    "data": {
      "providerAccount": [
        {
          "id": 10995860,
          "providerId": 16441,
          "isManual": false,
          "createdDate": "2017-12-22T05:47:35Z",
          "aggregationSource": "USER",
          "status": "IN_PROGRESS",
          "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
          "dataset": [
            {
              "name": "BASIC_AGG_DATA",
              "additionalStatus": "DATA_RETRIEVAL_IN_PROGRESS",
              "updateEligibility": "DISALLOW_UPDATE"
            }
          ]
        }
      ]
    }
  }
}

Account Summary Retrieved Event Response

{
	"event": {
		"info": "REFRESH.INTERIM_PROGRESS",
		"loginName": "fri21",
		"data": {
			"providerAccount": [{
				"id": 10995860,
				"providerId": 16441,
				"lastUpdated": "2017-12-21T18:30:00Z",
				"isManual": false,
				"createdDate": "2017-12-22T05:47:35Z",
				"aggregationSource": "USER",
				"status": "IN_PROGRESS",
                                "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
				"dataset": [{
					"name": "BASIC_AGG_DATA",
					"additionalStatus": "ACCT_SUMMARY_RECEIVED",
					"updateEligibility": "DISALLOW_UPDATE"
				}]
			}]
		}
	}
}

REFRESH.PROCESS_COMPLETED

Process Completed Success Event Response

{
	"event": {
		"info": "REFRESH.PROCESS_COMPLETED",
		"loginName": "fri21",
		"data": {
			"providerAccount": [{
				"id": 10995860,
				"providerId": 16441,
				"isManual": false,
				"createdDate": "2017-12-22T05:47:35Z",
				"aggregationSource": "USER",
				"status": "SUCCESS",
                                "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
				"dataset": [{
					"name": "BASIC_AGG_DATA",
					"additionalStatus": "AVAILABLE_DATA_RETRIEVED",
					"updateEligibility": "ALLOW_UPDATE",
					"lastUpdated": "2017-12-22T05:48:16Z",
					"lastUpdateAttempt": "2017-12-22T05:48:16Z"
				}]
			}]
		}
	}
}

Process Completed Failure Event Response

{
	"event": {
		"info": "REFRESH.PROCESS_COMPLETED",
		"loginName": "fri21",
		"data": {
			"providerAccount": [{
				"id": 10995860,
				"providerId": 16441,
				"isManual": false,
				"createdDate": "2017-12-22T05:47:35Z",
				"aggregationSource": "USER",
				"status": "FAILED",
                                "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
				"dataset": [{
					"name": "BASIC_AGG_DATA",
					"additionalStatus": "DATA_RETREIVAL_FAILED",
					"updateEligibility": "ALLOW_UPDATE",
					"lastUpdated": "2017-12-22T05:48:16Z",
					"lastUpdateAttempt": "2017-12-22T05:48:16Z"
				}]
			}]
		}
	}
}
Note: The status and additionalStatus values may vary depending on the type of failure. Customers have to refer to the different types of status and additional status for effective implementation.

 


Best Practices

  • User input required events are time-bound. When the notification is received, customers should ask for the MFA information from users and post it to the relevant Yodlee API before the process gets timed out.
  • If you have subscribed for notifications, customers should not call the get provider account API; this action can prevent Yodlee from notifying customers for the user input required event and may lead to add/update account failures.
  • Yodlee does not recommend customers having implementations with different API versions. The refresh webhooks will always use the latest API version format in such cases.
  • When the providerAccount is not eligible to be called in the update account API, the reason will be given to customers in the update account response as API errors. Notifications will not be sent to customers in such cases.
  • There are possibilities that add or update account process takes a longer time. Customers need not hold users on the screen; communicate to them that the process is taking longer than usual and provide them options to proceed with other associated activities.


FAQs

What does refresh mean?
Refresh is the process of adding accounts from the provider site or updating the already added accounts with the latest information.

Do notifications get delayed? How do we handle the same?
Yes, there are possibilities where the provider does not respond or takes a longer time than usual.
If you don’t receive a response within a specific time period, inform the users that the process is taking longer than usual and ask them to proceed with other associated activities. Yodlee will still send notifications once the process is completed.