Every change to a policy is recorded as an immutable policy event. Events are appended in order, are never edited, and together form the full history of the policy. They are the record you should reconcile against, rather than the current policy object alone.

You receive policy events in two ways:

• Webhooks push an event to your endpoint as it happens. See Webhooks.
• The policy events endpoint returns the full history on demand. See List policy events.

Both surfaces are produced by the same output mapping, so an event has the same type and field names whether it arrived by webhook or was retrieved later.

This guide explains the shape of an event, which events each type of policy change produces and in what order, how to interpret events that can carry different kinds of change, and how to read the premium fields on an event.

The event envelope

Every policy event carries the same common fields, followed by fields that are specific to its type.

requested_by.type

Example of a minimal event:

{
  "policy_id": "7a4f4a7e-2b0e-4a4b-9a1e-6b3c7e2a9d10",
  "type": "policy_activated",
  "event_version": 4,
  "created_at": "2026-03-02T08:15:41.120Z",
  "requested_by": {
    "type": "system"
  },
  "metadata": {
    "requested_by": { "type": "system" },
    "requested_at": "2026-03-02T08:15:41.099Z"
  }
}

Where events are delivered

Webhooks

A policy webhook delivery has this body:

The name of the subscription that triggered the delivery is not in the body. Always discriminate on event.type. In one case a subscription delivers an event of a different type; see Notes for reconciliation.

Retrieving the event history

List policy events returns every event on a policy, newest first. The endpoint is not paginated; use created_at_from, created_at_to, version_from and version_to to narrow the range on policies with long histories. Use it to backfill, to recover from a missed webhook, or to look up the state of a policy immediately before a given event.

Events by policy change

Each section lists the events in the order they are recorded, and then the events that follow asynchronously. Events marked async are queued after the request completes and can arrive out of order relative to each other.

Policy issue

1. policy_issued — the full initial state of the policy.
2. text_note_created — one per note carried over from the application, if any.
3. policy_activated — if the product is configured to activate on issue. Otherwise it is recorded later, when the configured activation event occurs (for example the first successful payment).
4. payment_method_assigned — if a payment method was supplied on the application.
5. async policy_terms_updated, policy_schedule_updated, policy_welcome_letter_updated and policy_certificate_updated as each document is generated.

The policy_issued event carries: policy_number, package_name, sum_assured, monthly_premium, base_premium, billing_frequency, billing_amount, billing_month, billing_day, beneficiaries, start_date, end_date, module, app_data, restricted_data, application_id, policyholder_id, scheme_type, covered_items, currency, product_module_id, product_module_definition_id, payment_method_id, charges, status and field_changes.

Alteration packages

An alteration is any post-issue change made through an alteration hook: a change of cover, a change of premium, a change of policy details, or all three. It happens in two steps.

Create. Calling the create alteration package endpoint runs the hook and stores a package with status: "pending". No policy event is recorded. The alteration_package_created webhook is sent with the package object.

Apply. Applying the package records exactly one policy event, policy_alteration_package_applied, and sets the package status to "applied". No policy_updated event is recorded for an alteration.

1. policy_alteration_package_applied
2. async policy_schedule_updated, and policy_certificate_updated where the product issues certificates.

Cancellation and reactivation

1. policy_cancelled. No document event follows a cancellation; notifications are sent but nothing further is recorded on the policy.

If the product's beforePolicyCancelled lifecycle hook prevents the cancellation, the cancel request fails with an error and no event is recorded. policy_cancel_failed is recorded only when a scheduled cancellation (one created with a future action date through the bulk cancel endpoint) cannot be actioned on that date, for example because the policy was cancelled in the meantime. It carries failure_reason.

Reactivating a cancelled or lapsed policy records policy_reactivated with status (the status the policy returned to), reactivation_option (the option object from your product module, including its type), module if the reactivation hook changed it, and field_changes. A policy_schedule_updated event follows asynchronously.

Lapse, expiry and not taken up

These are status changes made by the platform's scheduled processes, so requested_by.type is usually system. Each carries only the common envelope unless stated.

Other policy updates

Payment methods and billing instruments

Full event type reference

* Delivered with type: "policy_altered" and an alteration field. See Notes for reconciliation.

Interpreting policy_updated

policy_updated records a change to one or more top-level policy fields that did not go through an alteration hook. The event carries only the fields that were set, all optional, with no wrapper object:

app_data, billing_day, billing_month, billing_amount, package_name, sum_assured, base_premium, monthly_premium, start_date, end_date, policy_number, policyholder_id, module, restricted_data, lapse_and_ntu_prevention_start_date, lapse_and_ntu_prevention_end_date, field_changes.

There is no reason or source field. To determine what caused a policy_updated, combine the fields present with requested_by.type:

When field_changes is enabled, prefer it over the presence of fields: it lists only what actually changed, whereas a field can be present on the event with the same value it already had.

{
  "policy_id": "7a4f4a7e-2b0e-4a4b-9a1e-6b3c7e2a9d10",
  "type": "policy_updated",
  "event_version": 9,
  "created_at": "2026-04-14T10:02:17.503Z",
  "requested_by": {
    "type": "product_module"
  },
  "billing_day": 25,
  "module": {
    "type": "funeral_cover",
    "cover_amount": 3000000,
    "commission_percentage": 12.5
  },
  "field_changes": [
    { "path": "billingDay", "before": 1, "after": 25 },
    { "path": "module.commissionPercentage", "before": 10, "after": 12.5 }
  ]
}

Detecting a premium change on an alteration

Every policy_alteration_package_applied event carries monthly_premium, whether or not the premium changed. There is no flag that says "this alteration affected the premium". Determine it from the data:

1. If field_changes is present, look for an entry with path equal to monthlyPremium. Its absence means the premium did not change.
2. Otherwise, compare the event's monthly_premium to the policy's monthly_premium immediately before the event. That is the monthly_premium on the most recent earlier event that carries one (policy_issued, policy_alteration_package_applied, policy_updated, policy_premium_updated, policy_members_updated or policy_requoted).

A premium-neutral alteration, for example a corrected vehicle registration:

{
  "type": "policy_alteration_package_applied",
  "event_version": 6,
  "alteration_package_id": "b3d2f0a1-5c7e-4d0a-8f4b-2e1c9a7d6f30",
  "alteration_key": "update_vehicle_details",
  "alteration_name": "Update vehicle details",
  "package_name": "Comprehensive",
  "sum_assured": 25000000,
  "monthly_premium": 84900,
  "base_premium": 79900,
  "billing_amount": 84900,
  "module": { "type": "motor", "registration": "CA 123 456" },
  "field_changes": [
    { "path": "module.registration", "before": "CA 123 465", "after": "CA 123 456" }
  ]
}

A premium-affecting alteration, for example an increase in cover:

{
  "type": "policy_alteration_package_applied",
  "event_version": 7,
  "alteration_package_id": "0c8e6b12-9d3a-4e5f-b7a1-4f2d8c1e9a55",
  "alteration_key": "change_cover",
  "alteration_name": "Change cover amount",
  "package_name": "Comprehensive",
  "sum_assured": 30000000,
  "monthly_premium": 97200,
  "base_premium": 91500,
  "billing_amount": 97200,
  "module": { "type": "motor", "registration": "CA 123 456" },
  "field_changes": [
    { "path": "sumAssured", "before": 25000000, "after": 30000000 },
    { "path": "monthlyPremium", "before": 84900, "after": 97200 },
    { "path": "basePremium", "before": 79900, "after": 91500 },
    { "path": "billingAmount", "before": 84900, "after": 97200 }
  ]
}

The difference between the two premiums (here 12 300 cents per month) is not stored on the event. For policies billed on a payment schedule the platform records the signed monthly difference internally so that the next scheduled amount tracks the new premium; that record is not exposed as a policy event or webhook.

Premium fields on events

Applying an alteration does not create a pro-rata charge or refund for the period already billed. If your product needs to charge or refund for a mid-cycle change, raise it from the product module using a change policy balance action, which then appears in the policy's payment data rather than as a policy event.

Linking events to the policy and to each other

Notes for reconciliation