> ## Documentation Index
> Fetch the complete documentation index at: https://developer.plugsurfing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

Consume Drive API session event webhooks, handle unordered delivery, and keep charging status tracking resilient.

## Description

Plugsurfing can notify you when a session event happens for either:

* a user session
* a fleet (B2B charging key) session

These events are sent to you using [webhooks](https://en.wikipedia.org/wiki/Webhook).

For a webhook overview (including security and HMAC), start with [Webhooks](/docs/drive-api/webhooks).

Each event will be pushed once without retries. The listener's response is not taken into account.\
Events are distributed in the same way for both remote and local (RFID) sessions.

<Info>
  Event type should be checked before processing. New event types can appear without previous notice.
</Info>

<Danger>
  We do not guarantee the delivery of events. Some Charge Point Operators (CPOs) may fail to send events, and events may be received in an unexpected order.\
  For instance, a `SESSION_START_FAILED` event might be followed by a `SESSION_STARTED` event (e.g. if the CPO had connection issues with the charger).
  Session events are intended to enhance the user experience, but your system should be designed to function independently of them.
  For more information, see [Remote session](/docs/drive-api/sessions#remote-charging).
</Danger>

## Configuration

Events can be configured on stage environment directly from the Control Panel.\
For production setup you need to contact your account manager.

Data needed for configuration:

* **Url** that will receive all events
* **Authorization headers** that will be passed in the request to the mentioned url.

## Request

Method: **POST**

**Body fields:**

* `event` (string) - possible event names listed below\
  (remember to gracefully handle other events, that might be added in the future)
* `payload` (object) - defined for each event

**User session example:**

```json theme={null}
{
  "event": "SESSION_STARTED",
  "payload": {
    "userId": "user1",
    "sessionId": "L60XMxWy0oP",
    "timestamp": "2025-06-12T10:56:51Z"
  }
}
```

**Fleet session example:**

```json theme={null}
{
  "event": "SESSION_STOPPED",
  "payload": {
    "fleetId": "fleet_123",
    "keyIdentifier": "e0e03336",
    "visualNumber": "DE*8PS*FR1RFK*4",
    "contractId": "DE-8PS-C0AD21B13-Q",
    "sessionId": "L60XMxWy0oP",
    "timestamp": "2025-06-12T11:31:02Z"
  }
}
```

**Fee incurring example (user session):**

```json theme={null}
{
  "event": "SESSION_FEE_INCURRING",
  "payload": {
    "sessionId": "L60XMxWy0oP",
    "timestamp": "2025-10-15T08:52:48Z",
    "userId": "user1",
    "feeWillApplyFrom": "2025-10-15T09:02:48Z",
    "feeType": "BLOCKING"
  }
}
```

## Payload variants (user vs fleet)

All session events use the same envelope:

* `event` (string)
* `payload` (object)

All payloads contain:

* `sessionId` (string)
* `timestamp` (datetime, ISO 8601 / RFC 3339)

For user sessions:

* `userId` (string)

For fleet sessions (no user concept):

* `keyIdentifier` (string)
* `fleetId` (string, usually present)
* `visualNumber` (string, optional)
* `contractId` (string, optional)

<Info>
  A session event payload contains either user fields or fleet fields. For fleet sessions, `userId` is not present by design.
</Info>

## Event types

### Session started

This event is provided for most remote sessions and for many local (rfid) sessions.\
To get more details like session start date, you can use the [session-by-id](/reference/getSessionById) endpoint.

event name: **`SESSION_STARTED`**

payload: user or fleet variant (see section above)

### Session failed

If a session fails to start properly, this event is sent and the session goes to FAILED status.
`SESSION_START_FAILED` is emitted for failed start outcomes (denied, rejected, failed).

event name: **`SESSION_START_FAILED`**

payload: user or fleet variant (see section above)

### Session progress

This event is sent during an ongoing charging session when Plugsurfing receives updated energy data from the Charge Point Operator (CPO).

Multiple `SESSION_PROGRESS` events may be sent during the same session as the delivered energy value is updated.

event name: **`SESSION_PROGRESS`**

payload:

* user or fleet variant (see section above)
* `energy` (object)
  * `unit` – Wh
  * `value` – energy delivered during the session

`SESSION_PROGRESS` is available on chargers where the CPO supports and sends ongoing energy updates. If no progress data is received from the CPO, no `SESSION_PROGRESS` events are sent.

### Session incurring fee

This event is sent to notify that a session might incur some fee that is not related to charging. The incurring feeType further explains why the fee will be applied.

event name: **`SESSION_FEE_INCURRING`**

payload:

* `sessionId` (string)

* `timestamp` (datetime, ISO 8601 / RFC 3339)

* `userId` (string, user sessions only)

* `keyIdentifier` (string, fleet sessions only)

* `fleetId` (string, fleet sessions only)

* `visualNumber` (string, optional, fleet sessions only)

* `contractId` (string, optional, fleet sessions only)

* `feeWillApplyFrom` (datetime, ISO 8601 / RFC 3339)

* `feeType` (string/enum) - can be one of `CONGESTING`, `PARKING`, `BLOCKING`

* **feeWillApplyFrom**: the time from which the fee will be applied if the session is not stopped before that time.

* Each fee type corresponds to a specific scenario:
  * BLOCKING: Triggered when charging period of a vehicle exceeds a given threshold. The event is emitted 10 minutes before blocking fees start, giving the user time to stop the charging session and leave the location.
  * PARKING: Triggered when a vehicle has finished charging but remains connected to the charger. The event is emitted immediately when parking fees start.
  * CONGESTING: Triggered when a vehicle occupies a charger during peak times. Events of this type are published only for Tesla-owned chargers and only if you have explicitly subscribed to the Tesla Network. Tesla requires that this event be delivered to users via push notification. The event is emitted immediately when congestion fees start.

### Session stopped

This event is sent right after a remote session stops successfully.

event name: **`SESSION_STOPPED`**

payload: user or fleet variant (see section above)

### Session stop failed

This event is sent when there is an issue with stopping a session. The session goes into `STOP_FAILED` status.\
The user should be able to request a stop once again.
`SESSION_STOP_FAILED` is emitted for failed stop outcomes (denied, failed).

event name: **`SESSION_STOP_FAILED`**

payload: user or fleet variant (see section above)

### Session completed

This event will be sent when the session has been priced and:

* the payment is successful in case Plugsurfing is the Merchant on Record
* the CDR has been successfully sent to the customer otherwise

This event cannot be generated until Plugsurfing receives the session's [CDR](/docs/drive-api/cdr) from the CPO.

<Danger>
  In some rare cases where we receive the CDR late, this event can arrive hours or even days after the session has actually finished.
</Danger>

To get more details about the session, use the [session-by-id](/docs/drive-api/sessions#get-session-by-id) endpoint.
Use the `balanceStatus` and the `balanceAmountMinor` on the sessions to assess if the payment is currently successful or not.

event name: **`SESSION_COMPLETE`**

payload: user or fleet variant (see section above)

## Examples

**Session started example (user session):**

```json theme={null}
{
  "event": "SESSION_STARTED",
  "payload": {
    "userId": "user1",
    "sessionId": "L60XMxWy0oP",
    "timestamp": "2025-06-12T10:56:51Z"
  }
}
```

**Session stopped example (fleet session):**

```json theme={null}
{
  "event": "SESSION_STOPPED",
  "payload": {
    "fleetId": "fleet_123",
    "keyIdentifier": "e0e03336",
    "visualNumber": "DE*8PS*FR1RFK*4",
    "contractId": "DE-8PS-C0AD21B13-Q",
    "sessionId": "L60XMxWy0oP",
    "timestamp": "2025-06-12T11:31:02Z"
  }
}
```

**Session progress example (user session):**

```json theme={null}
{
  "event": "SESSION_PROGRESS",
  "payload": {
    "userId": "user1",
    "sessionId": "L60XMxWy0oP",
    "timestamp": "2026-08-11T13:26:00.435Z",
    "energy": {
      "unit": "Wh",
      "value": "44400"
    }
  }
}
```

**Fee incurring example (user session):**

```json theme={null}
{
  "event": "SESSION_FEE_INCURRING",
  "payload": {
    "sessionId": "L60XMxWy0oP",
    "timestamp": "2025-10-15T08:52:48Z",
    "userId": "user1",
    "feeWillApplyFrom": "2025-10-15T09:02:48Z",
    "feeType": "BLOCKING"
  }
}
```

## Security

If you want to be sure that events you receive are emitted by Plugsurfing, please check the [Verify HMAC Signatures](/docs/drive-api/verifying-hmac-signature) guide.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.