Introduction

When building on Canopy, it is extremely valuable to think of a borrower lifecycle as a sequence of events, each with a timestamp and its own business logic.

Because Canopy is an immutable system of record, the events framework allows you to conceptualize how each of your actions modify the Computational State of an Account in conjunction with the natural passage of time. Rather than writing to and updating state, each of your write interactions with the API, regardless of whether it is constructive, mutative, or deletory in nature, in your mental model should be thought of as a new event in the immutable history of events for the account.

Reasoning About Events

Accounts created in Canopy have multiple events occur over the account lifecycle. You should be conscious of two categories of events

Scheduled Events

Automatically Scheduled Based on Configurations

Automatically scheduled events are scheduled by Canopy based on the Policy Configurations that are set to drive that account's behavior. For instance, the cycle_interval set in the Products API governs the scheduling of statement events to correspond with the end of each billing cycle for a borrower. Key examples include billing cycle dates, due dates, and autopay scheduling.

Canopy's events engine enforces that the system responds to all of these events per configured rules, and thus can also serve as the reliable source of truth for information around these events from external systems. For example -- based on a configured promotional period for an account, Canopy will automatically end promotional policies on a date that was configured when the account was created.

Caller Scheduled

Certain events may be scheduled by the caller as well. A reference example can be found in the Schedule the update of an existing line item API endpoint. Callers pass an effective_at parameter that designates the point in time at which the event will occur. ~~Additional automatic or ~~

Atomic Events Based on Account Activity

While there is an overall schedule of activity planned and scheduled for a borrower, certain activity may occur atomically. These events are also part of the general timeline of events. For example - if a late fee assessment is scheduled to run on April 6th, a payment may atomically occur on April 5th. Because this payment occurred, the results of the future late fee assessment will be different than they would have been if the payment never occurred.

Running the same sequence of events with and without the payment creates an entirely different computational state of the account on April 6th.

Examples of atomic events include account edits, transactions, payments, etc. These typically occur through direct user interactions that call to Canopy's API.

Reasoning About Computational State

Any changes to the computational state of an account are encapsulated in the sequence of events that occurred to produce the current computational state.

Using Simulation Systems for Visibility

Canopy's simulation systems are designed to allow operators of lending programs to walk through the exact sequence of events, forwards and backwards in time to understand how each event affects the Computational State of an Account. The best mechanism for building intuition around how each type of event modifies the computational state is to use LoanLab - an out of the box simulation environment that helps you understand the effects of each event in Canopy without being a technical user of the API.

Powering External Activity

All events in Canopy fire webhooks that are designed to power your downstream systems. For example, you may want to create an alert or schedule an email based on certain forms of event activity.

Check out our Webhooks documentation to understand how to respond to events in Canopy.