# session.updated

> The session.updated webhook fires whenever a charging session changes state or its energy and cost figures are updated.

This page documents the `session.updated` event payload. For the envelope shape, headers, signature scheme, retries, and idempotency rules that apply to every webhook, see [Webhooks](/docs/charge-now/guides/webhooks).

## When it fires

`session.updated` is emitted whenever a charging session changes state or when its energy/cost figures are revised. In practice you will see one event per state transition (`Pending`, `Starting`, `Started`, `Stopping`, `Stopped`, `Settled`, `Failed`, `Abandoned`) and one event when a settlement correction lands.

## Payload shape

The `data` field is the public `Session` object, the same shape returned by `GET /sessions/{id}`, so you can deserialise it with the model you already use. The full envelope, delivery headers and payload are in the [session.updated reference](/docs/charge-now/reference/chargenow-api/webhooks#sessionupdatedwebhook), machine-readable. New keys may appear over time; ignore unknown ones to stay forward-compatible.

### Example: session that just started

```json
{
  "specversion": "1.0",
  "id": "5b9d6c1a-3d2f-5e88-9c1f-1a5b2e0e8e1a",
  "type": "session.updated",
  "source": "charge-now/api",
  "time": "2026-06-15T10:14:22.482931Z",
  "datacontenttype": "application/json",
  "data": {
    "id": "c5a7e1b2-4d3a-4c0e-b1f3-9c7b8d2e1a4f",
    "chargePointId": "31a4f0c2-5d10-4a8d-9b3a-2e0f1c7d8b6a",
    "state": "Started",
    "reference": "order-1042",
    "kwh": 4.2,
    "cost": 1.78,
    "currency": "EUR",
    "startedAt": "2026-06-15T10:12:03Z"
  }
}
```

### Example: session that has settled

```json
{
  "specversion": "1.0",
  "id": "e10cf2b4-7a89-5b66-9d44-0a3b9f4d2e7c",
  "type": "session.updated",
  "source": "charge-now/api",
  "time": "2026-06-15T11:48:55Z",
  "datacontenttype": "application/json",
  "data": {
    "id": "c5a7e1b2-4d3a-4c0e-b1f3-9c7b8d2e1a4f",
    "chargePointId": "31a4f0c2-5d10-4a8d-9b3a-2e0f1c7d8b6a",
    "state": "Settled",
    "reference": "order-1042",
    "kwh": 18.74,
    "cost": 7.92,
    "currency": "EUR",
    "startedAt": "2026-06-15T10:12:03Z",
    "stoppedAt": "2026-06-15T11:46:31Z",
    "settlementVersion": 1
  }
}
```

## What a handler acts on

The full payload is in the [reference](/docs/charge-now/reference/chargenow-api/webhooks#sessionupdatedwebhook). In practice a handler keys on three things: `data.id` to correlate (and the envelope `id` to dedupe), `data.state` to react to the [transition](/docs/charge-now/guides/sessions), and `data.settlementVersion` to catch a settlement correction, where a value higher than you last stored means `cost` and `kwh` have changed. Remember `cost` excludes VAT and can be `null` until the network reports figures.

## Ordering considerations

Webhooks are at-least-once and not strictly ordered (see [Ordering and race conditions](/docs/charge-now/guides/webhooks#ordering-and-race-conditions) on the main webhooks page). For `session.updated` specifically:

- **Use the envelope `time` field** to determine which event is newer for a given `data.id`. The session state machine is monotonic for a single session except for settlement corrections (below), so a later `time` always wins.
- You may see `Settled` arrive before `Stopped` if the earlier delivery was retried. The envelope `time` reflects the order in which events were produced on our side, so use it as the source of truth.

## Settlement corrections

In rare cases the charging network sends a correction after the initial settlement, for example to fix a metering error or revise a tariff. When that happens, a session that already reached `Settled` emits another `session.updated` event, still with `state: "Settled"` but with updated `cost`, `currency`, `kwh`, and an incremented `settlementVersion`.

- **Use `settlementVersion` to detect corrections.** If you receive a `session.updated` event with a higher `settlementVersion` than you last recorded, the `cost` and `kwh` have changed and you should update your records.
- Corrections are accepted within **180 days** of the first settlement. After that window the values will not change.
- Compare the envelope `time` against the `time` of the last event you applied for the same session and take the later one. The `data` payload always reflects the latest confirmed figures.
- See [Settlement & Corrections](/docs/charge-now/guides/sessions/settlement) for the full explanation, cancellation corrections, and billing implications.