API reference

session.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.

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, machine-readable. New keys may appear over time; ignore unknown ones to stay forward-compatible.

Example: session that just started

{
  "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

{
  "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. 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, 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 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 for the full explanation, cancellation corrections, and billing implications.