What are (event) hooks?

Event hooks are blocks of code - typically JavaScript functions - that are used to configure product-specific functionality. They give you the ability to easily inject custom logic into certain events on the platform. This enables you to intercept and modify the platform's standard behaviour.

This functionality includes how premiums are calculated, determining what data is stored on policies when they are issued, and how policies can be changed after they are issued (among others).

Event hooks can be contrasted to standard platform functionality. For example, the process whereby policyholders are created is standard across all product modules, and does not require configuration. But the information required to calculate a premium and generate a quote (for example), is necessarily product specific, so a quote hook for each product needs to be configured to define its requirements and business rules.

Event hooks can be triggered in one of two ways. Some hooks are triggered by user initiated API calls, such as making call to the quote endpoint to get a quote. Other hooks are triggered by predefined events in a policy's lifecycle, such as a claim being approved or a premium collection attempt failing. Scheduled functions can also be defined to run at specified time intervals.

Some hooks return a result in a specific format, such as a new quote package, to be saved to the platform and returned over the API. Other hooks return actions to be performed, such as updating existing policy information. See the event hooks reference for a full list of supported hooks.

Hooks are configured as code functions in Root's low-code environment. Read more about product module code.

Hooks required to issue policies

The product module code needs to include at least the following hooks to allow policies to be issued. By defining these functions, you are customising how the quote, application, and policy API endpoints will function for your product. This includes specifying the required input parameters, the pricing logic, and the information that will be saved to the platform (and returned via the API) at each step.

• Quote hook
• Application hook
• Policy issue hook

Automated hooks

You may want to register automated actions to run for existing (issued) policies. These actions can be triggered either by a predefined event in the lifecycle of the policy (lifecycle hooks), or on a time-based schedule (scheduled functions).

Lifecycle hooks

Lifecycle hooks are predefined events that can occur during the lifecycle of a policy. When an event is triggered, you can specify certain actions to be performed automatically in relation to the policy. For example afterPaymentSuccess(), beforePolicyReactivated() or afterClaimApproved().

These are useful for things like dynamic cover changes or complex lapse rules. For more details, see the guide on lifecycle hooks.

Scheduled functions

As the name implies, scheduled functions run at regular, specified intervals. These functions perform recurring actions against existing policies, as defined in the product module code.

These are useful for things like implementing premium changes at the policy anniversary. For more details, see the guide on scheduled functions.

Actions

Actions are objects returned by lifecycle hooks and scheduled functions, and added to the platform's job queue to be executed. They can be used to update policy data, change policy status, and credit or debit the policy balance on the ledger, among others. A reference for all supported actions is provided in the actions guide.

User initiated hooks

These are hooks for existing policies that can be triggered ad hoc. Each hook is linked to a corresponding API call. Root dashboard workflows can be configured to allow dashboard users to trigger these hooks.

Alteration hooks

Alteration hooks are used to amend policies. They allow for flexible updates of policy data through a simple interface with minimal required fields. For example, should a customer want to correct the name of one of the lives covered under a funeral policy, this can be enabled by defining an alteration hook to capture the new information and apply it to the existing policy

An expanded alteration hook can also be defined to allow for a full policy requote, recapturing all rating factors and other required information, and recalculating the premium and other variable amounts. For more details, see the alteration hooks guide.

Reactivation

Reactivation means changing the status of an inactive (e.g. lapsed or cancelled) policy to active. Reactivation can be enabled or disabled in the product module settings. If reactivation is enabled, you will need to define the reactivation options in the product module code. You can also constrain reactivation to policies that meet specific criteria. For more details, see the guide on reactivation.

Requote

🚧

Deprecation warning

Requote functionality is in the process of being deprecated. Please use alteration hooks instead. This documentation is here for maintenance of older product modules.

Requoting is a way to amend or alter policy information after the policy has been issued. Whereas alteration hooks allow you to specify the information that will be captured, requote relies on the existing quote and application hooks as defined in the product module code. These hooks are used to create a new application, which can then be applied to the existing policy to update the policy information. More details can be found in the requote guide.