Overview

Custom notification events allow you to flexibly send notifications for events specific to an insurance product. For example, you can configure an event to send a regular notification to remind policyholders to update their details, or to inform specific policyholders of changes to their policy due to a pending benefit termination. These events can be triggered from the Product module code.

Custom notification events can be contrasted with standard notification events such as "Policy issued" or "Payment method updated". These events are triggered automatically based on pre-defined platform events.

In some cases, the same functionality can be achieved using either custom or standard events, with custom events offering a higher degree of flexibility and configurability. For example, instead of using the standard "Policy issued" event, you can use the afterPolicyIssued lifecycle hook to trigger a notification to customers.

Custom notification events also allow you to configure which policy documents are included as attachments with the email notification.

📘

Protected feature

Custom notification events is a protected feature, and is disabled by default. To enable this feature for your organisation, please contact our support team at [email protected].

Creating a custom notification event

Custom notification events are created from the Customer notifications tooling on the Root management dashboard.

When creating a custom notification event, you need to specify the event name and the event key. The event key must be a lowercase token, and must be unique. You will use this key to identify the event when it is triggered.

You also need to choose the event type - whether it will be a policy, payment method, payment, or claim event. Note: Payment method custom events can only be triggered for payment methods that have already been linked to a policy.

The type of event affects the notification in two ways:

• Merge variables - A different set of merge variables is made available to the email and SMS templates depending on the event type. To see which merge variables are available for your event, open the "Merge vars" pane when editing the notification template.
• Recipient - For policy, payment method, and payment events, the recipient is the policyholder. For claim events, the recipient is the claimant.

🚧

Be careful when archiving or editing a custom event

If you have any custom notification events in use, archiving or editing the event could break the implementation if the corresponding changes are not simultaneously implemented in the product module code. For example, if you change the event type from policy to claim, you will need to make a corresponding change in the product module code.

Attachments

For email notifications, you can select any (or none) of the following policy documents to be included as attachments:

• Terms file
• Policy schedule
• Welcome letter
• Anniversary letter
• Policy certificate

These attachments will be included irrespective of the product module settings. For example, even if the policy anniversary and welcome letter are disabled in the settings, these documents will still be generated and attached to the email (provided a valid template is defined for each attachment).

🚧

Sending a custom event email regenerates attachments

The attachments you select will be regenerated when the email notification is sent. The relevant policy documents associated with the policy will be replaced with the updated versions.

Triggering a custom notification event

Once you have created a custom notification event, you can trigger it in one of three ways:

• Returning an action from a lifecycle hook or scheduled function in the product module code
• Using the Root SDK method in the product module code
• Making an API call

Whichever method you use, you need to reference the key and the type of the custom notification event you want to trigger. If the key does not match an existing event key, or the specified type differs from the matching event type, the notification will not be sent.

Depending on the event type, you also need to specify the UUID of the entity you wish to trigger the event for (policy, payment, or claim). Note: For payment method custom events, you need to specify the policy_id. This is because payment method custom events can only be triggered for payment methods that have been linked to a policy.

For the custom notification to be sent, the email or SMS notification (or both) need to be enabled on the dashboard customer notifications tooling.

📘

Review your standard event configuration before implementing custom events

New custom events may overlap with existing standard events. For example, it's possible to have the standard "Policy reactivated" event enabled, and to implement a custom event that is triggered by the afterPolicyReactivated lifecycle hook. To avoid sending unnecessary notifications to your customers, make sure to disable standard events that are replaced by custom events.