What is Monitoring?

With Monitoring, you can continuously receive refreshed data for users that link their insurance accounts to you using Canopy Connect. Refreshing data is billed at the same price as a Pull. When Monitoring is enabled for a Pull, you will receive continuous updates on the interval you specify.

There are two flavors of monitoring:

Refresh data on all Pulls: Email support@usecanopy.com and confirm your desired interval for automatic refresh. We support automatic refreshing every X days, every X months, or every X years. Intervals must be >= 30 days.
Refresh specific Pulls with our API: Use the Monitoring API endpoints to enable or disable monitoring for specific Pulls.

How do I receive updates?

Canopy Connect's infrastructure will send you Webhook requests indicating there is refreshed data available. You will also receive Webhook requests if the consumer needs to provide input to reconnect their account.

Automatic refresh

The majority of Pulls will refresh without needing further input from the consumer. Canopy Connect infrastructure sends the POLICY_AVAILABLE, POLICIES_AVAILABLE and COMPLETE events via webhook requests when refreshed data is available. See Using Webhooks for details on these event types.

When consumer input is required

Consumer input is required when Canopy Connect cannot automatically refresh an insurance account. This can happen if the consumer has 2-factor authentication enabled or if their login credentials have changed.

Canopy Connect infrastructure sends a Webhook request with the MONITORING_RECONNECT event_type to indicate that consumer input is required. The Webhook request body contains the initial Pull ID and the developer-supplied meta_data from the initial Pull. Use the initial_pull_id or the meta_data to associate this event with an end-user in your application.

The MONITORING_RECONNECT webhook is a POST request with a JSON body of the form:

   {      
  "widget_id": "<WIDGET_ID>", // widget_id of the Widget the initial Pull was submitted on
  "pull_id": "<PULL_ID>", // pull_id of the new Pull
  "status": <STATUS>, // status of the new Pull at the time the event occurred
  "meta_data": {... developer-supplied JSON-serializable metadata from the initial Pull ...},
  "event_type": "MONITORING_RECONNECT", // webhook event type
  "is_monitored": true,
  "monitoring": {
    "initial_pull_id": "<PULL_ID>", // The ID of the initial Pull of the account
    "monitoring_id": "<MONITORING_ID" // ID of the Monitoring object
  },
  "data": { 
    // One of NOT_AUTHENTICATED, IDENTIFTY_VERIFICATION_OPTIONS, IDENTITY_VERIFICATION
    "auth_status": "<STATUS>", 
    // For non-whitelabel users, URL you can send to consumers to reconnect their account
    "reconnect_url": "https://app.usecanopy.com/c/<ALIAS>/reconnect?reconnectToken=<RECONNECT_TOKEN>",
    // For whitelabel users, token that can be used with the POST /refreshToken route
    "reconnect_token": "<RECONNECT_TOKEN>",
  }
}

How to reconnect an account when consumer input is required

Use our pre-built UI to reconnect the account: The Webhook request contains a reconnectUrl URL which you can send to the end-user to reconnect their account. Send the URL via text message, email or link to it from your website to prompt the user to reconnect their account.
Reconnect the account using our SDK: Follow the Using the SDK guide but instead of passing the consentToken option to CanopyConnect.create(…), use the reconnectToken value taken from the MONITORING_RECONNECT webhook payload. Note that reconnectToken values can expire, so you call the POST /reconnectToken endpoint first to get a fresh token.
Reconnect the account from your website or app: Reconnecting the account from your application yields the highest conversion because end-users can reconnect without leaving your app, and you can leverage your own user interface elements.
Reconnect the account by calling the POST /widget/pull/reconnectToken endpoint with x-canopy-client-id and x-canopy-client-secret headers and the reconnect_token from the MONITORING_RECONNECT Webhook. The HTTP response body contains a pull_id and pull_jwt that you use when calling the POST /connect, POST /idvoptions and POST /idv endpoints.

Await the AUTH_STATUS webhook event to display the appropriate prompt to your end-user. Refer to the table below to guide the end-user through the account reconnect experience from your application. Use the auth_status value from the webhook request body to determine what to display and the next step in your app.

auth_status	Meaning	Display	Next step
NOT_AUTHENTICATED	Login credentials have changed.	Prompt end-user for new login credentials.	Call POST /connect with new login credentials. Await the AUTH_STATUS webhook event.
IDENTITY_VERIFICATION_OPTIONS	End-user must select 2-factor authentication method.	Have your end-user select their preferred option from the webhook request body.	Call POST /idvoptions with their selected option. Await the AUTH_STATUS webhook event.
IDENTITY_VERIFICATION	End-user is receiving a 2-factor authentication code.	Prompt end-user to supply the authentication code.	Call POST /idv with the provided code. Await the AUTH_STATUS webhook event.
SUCCESS	Authentication success.	Indicate to end-user they successfully authenticated their account.	Await `POLICY_AVAILABLE`, `POLICIES_AVAILABLE` and `COMPLETE` webhook events. When you receive a webhook request of new data becoming available, fetch the data by calling GET /pulls/:pullId .

See Using Webhooks for more information about our web hook events and how to register webhooks.