> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kota.io/core-components/webhooks-and-events/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server.

# Webhooks and Events

## Docs

- [Working with Events](https://docs.kota.io/core-components/webhooks-and-events/working-with-events.md): Guide to working with events and webhooks


> **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kota.io/core-components/webhooks-and-events/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server.

# Overview

> Handle asynchronous events from Kota via webhooks

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

> **Info**
>
> 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:**

```json
{
  "required_action": {
    "reason": "Additional information needed",
    "reason_description": "Your health insurance quote requires additional company information to proceed.",
    "due_at": "2024-02-15T17:00:00Z"
  }
}
```

> **Warning**
>
> 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

* [Events & webhooks API reference](/api-reference/events-and-webhooks)
* [Complete list of events](/api-reference/events-and-webhooks/types-of-events-v-2/employee-created-v-2-webhook)