Events

Description

Plugsurfing can notify you when a session event for any of your users happens, for example "charging session started" or "charging session stopped". These events are sent to you using 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.

📘

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

❗

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.

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

Example:

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

{
  "event": "SESSION_FEE_INCURRING",
  "payload": {
    "sessionId": "L60XMxWy0oP",
    "timestamp": "2025-10-15T08:52:48Z",
    "feeWillApplyFrom": "2025-10-15T09:02:48Z",
    "feeType": "BLOCKING"
  }
}

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

event name: SESSION_STARTED

payload:

• userId (string)
• sessionId (string)
• timestamp (datetime, ISO 8601 / RFC 3339)

Session failed

If a session fails to start properly, this event is sent and the session goes to FAILED status.

event name: SESSION_START_FAILED

payload:

• userId (string)
• sessionId (string)
• timestamp (datetime, ISO 8601 / RFC 3339)

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)

• 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:

• userId (string)
• sessionId (string)
• timestamp (datetime, ISO 8601 / RFC 3339)

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.

event name: SESSION_STOP_FAILED

payload:

• userId (string)
• sessionId (string)
• timestamp (datetime, ISO 8601 / RFC 3339)

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 from the CPO.

❗

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

To get more details about the session, use the 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:

• userId (string)
• sessionId (string)
• timestamp (datetime, ISO 8601 / RFC 3339)

Security

If you want to be sure that events you receive are emitted by Plugsurfing, please check the Verify HMAC Signatures guide.