Webhooks and Events

Overview

Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new Event object. For example, when an employer creates a health insurance quote, we create a employer.health_insurance.quote.created event, and when the insurer responds with a quote, we create an employer.health_insurance.quote.action_required event. Certain actions might create multiple events. For example, if an employee is offered an opt-out health insurance policy, you will receive both a employee.health_insurance.policy.created event and an employee.health_insurance.policy.

Events occur when the state of another API resource changes. The event’s data field embeds the resource’s state at the time of the change. For example, a employer.health_insurance.quote.action_required event contains an employer health insurance policy object, and an employer.health_insurance.quote.not_undertaken event also contains an employer health insurance quote object.

As with other API resources, you can use endpoints to retrieve an individual event or a list of events from the API. This connects to our webhooks system for sending the Event objects directly to an endpoint on your server. You can manage webhooks by reaching out to your contact at Kota, endpoints for managing them are coming soon.

When using Kota Embedded, you can also receive event notifications that occur within your user’s sessions so you can react to their activity, such as an employer creating a health insurance quote or an employee finalising their renewal.

We only guarantee access to events through the Retrieve Event API for 30 days.

Use webhooks to capture events that occur in your Kota integration. Webhooks are essential for handling asynchronous events and triggering additional actions in your platform.

Critical Events to Handle

Certain events require immediate action to ensure employers and employees are informed of time-sensitive developments:

  • employer.health_insurance.quote.action_required - Employer must take action on their health insurance quote
  • employee.health_insurance.offer.action_required - Employee must take time-sensitive action on their policy offer
  • Future events for policy renewal windows

We consider handling these events and immediately notifying your users as critical to a successful integration.

Communicating Required Actions

Events with action_required typically contain a required_action object to help you present information clearly to end users.

Using the required_action object:

  • reason - Use as the message title
  • reason_description - Use as the message body
  • due_at - Display the deadline prominently

Example:

1{
2  "required_action": {
3    "reason": "Additional information needed",
4    "reason_description": "Your health insurance quote requires additional company information to proceed.",
5    "due_at": "2024-02-15T17:00:00Z"
6  }
7}

Using Kota’s messaging helps ensure you don’t accidentally step into regulated activities by using your own language around insurance sales and renewals. Consider making it clear the language is from Kota’s platform.

Resources