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

# Event Types

This page provides detailed information about each webhook event type, including payload structures and examples.

## ocpp.message

The `ocpp.message` event is triggered whenever an OCPP message is sent to or received from a charging station. This provides real-time visibility into all communication between the Nayax Energy Core platform and your charging infrastructure.

### OCPP RPC Framework

OCPP (Open Charge Point Protocol) uses a JSON-RPC-like framework for communication between the central system (Nayax Energy Core) and charging stations. Understanding the message types is essential for processing these webhooks correctly.

#### Message Types

| Message Type  | Description                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `CALL`        | A request message that initiates an action. Contains an `action` name and a `payload` with parameters.   |
| `CALL_RESULT` | A successful response to a `CALL`. Contains only a `payload` with the result data.                       |
| `CALL_ERROR`  | An error response to a `CALL`. Contains an `errorCode`, `errorDescription`, and optional `errorDetails`. |

#### Message Correlation

Every OCPP message includes a `messageId` field. This ID is used to correlate requests with their responses:

1. A `CALL` message is sent with a unique `messageId`
2. The recipient responds with either a `CALL_RESULT` or `CALL_ERROR` using the **same** `messageId`

This allows you to match responses to their original requests when processing webhooks.

```
Station                           Nayax
   │                                │
   │  CALL (messageId: "abc123")    │
   │  Action: BootNotification      │
   │ ─────────────────────────────► │
   │                                │
   │  CALL_RESULT (messageId: "abc123")
   │ ◄───────────────────────────── │
   │                                │
```

#### Supported Protocols

The `protocol` field indicates which OCPP version the station is using:

* `ocpp1.6` - OCPP 1.6 (JSON)
* `ocpp2.0.1` - OCPP 2.0.1

### Payload Structure

The `data` object in an `ocpp.message` webhook contains:

| Field                 | Type   | Description                                          |
| --------------------- | ------ | ---------------------------------------------------- |
| `asset.id`            | string | The unique identifier of the charging station        |
| `connection.id`       | string | The unique identifier for this connection session    |
| `connection.protocol` | string | The OCPP protocol version (`ocpp1.6` or `ocpp2.0.1`) |
| `log`                 | object | The OCPP message details (varies by message type)    |
| `timestamp`           | string | ISO 8601 timestamp when the message was received     |

### Examples

#### CALL - BootNotification (Station to Nayax Energy Core)

When a charging station connects to the network, it sends a `BootNotification` to register itself:

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF789",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL",
      "messageId": "1705315800000",
      "action": "BootNotification",
      "payload": "{\"chargePointVendor\":\"ExampleVendor\",\"chargePointModel\":\"Model X\",\"chargePointSerialNumber\":\"SN123456\",\"firmwareVersion\":\"1.0.0\"}"
    },
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}
```

#### CALL\_RESULT - BootNotification Response (Nayax Energy Core to Station)

The response to a successful `BootNotification`:

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF790",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T10:30:00.100Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL_RESULT",
      "messageId": "1705315800000",
      "payload": "{\"status\":\"Accepted\",\"currentTime\":\"2024-01-15T10:30:00.100Z\",\"interval\":300}"
    },
    "timestamp": "2024-01-15T10:30:00.100Z"
  }
}
```

#### CALL - Heartbeat (Station to Nayax Energy Core)

Stations send periodic `Heartbeat` messages to indicate they are still connected. The interval is determined by the `interval` field in the `BootNotification` response (e.g., every 300 seconds):

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF7A0",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T10:35:00.000Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL",
      "messageId": "1705316100000",
      "action": "Heartbeat",
      "payload": "{}"
    },
    "timestamp": "2024-01-15T10:35:00.000Z"
  }
}
```

#### CALL\_RESULT - Heartbeat Response (Nayax Energy Core to Station)

The response contains the current server time, which stations use to synchronize their clocks:

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF7A1",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T10:35:00.050Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL_RESULT",
      "messageId": "1705316100000",
      "payload": "{\"currentTime\":\"2024-01-15T10:35:00.050Z\"}"
    },
    "timestamp": "2024-01-15T10:35:00.050Z"
  }
}
```

#### CALL - StartTransaction (Station to Nayax Energy Core)

When a charging session begins:

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF791",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T11:00:00.000Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL",
      "messageId": "1705317600000",
      "action": "StartTransaction",
      "payload": "{\"connectorId\":1,\"idTag\":\"RFID123456\",\"meterStart\":0,\"timestamp\":\"2024-01-15T11:00:00.000Z\"}"
    },
    "timestamp": "2024-01-15T11:00:00.000Z"
  }
}
```

#### CALL - MeterValues (Station to Nayax Energy Core)

Periodic energy consumption updates during charging:

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF792",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T11:15:00.000Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL",
      "messageId": "1705318500000",
      "action": "MeterValues",
      "payload": "{\"connectorId\":1,\"transactionId\":12345,\"meterValue\":[{\"timestamp\":\"2024-01-15T11:15:00.000Z\",\"sampledValue\":[{\"value\":\"7500\",\"unit\":\"Wh\",\"measurand\":\"Energy.Active.Import.Register\"}]}]}"
    },
    "timestamp": "2024-01-15T11:15:00.000Z"
  }
}
```

#### CALL - StatusNotification (Station to Nayax Energy Core)

Stations send `StatusNotification` messages whenever a connector's status changes. The payload contains a `status` field indicating the connector state and an `errorCode` field for fault detection.

**Connector Statuses (OCPP 1.6):**

| Status          | Description                                                   |
| --------------- | ------------------------------------------------------------- |
| `Available`     | Connector is available for a new session                      |
| `Preparing`     | Connector is preparing for a session (e.g., cable plugged in) |
| `Charging`      | Connector is actively charging a vehicle                      |
| `SuspendedEV`   | Charging suspended by the vehicle                             |
| `SuspendedEVSE` | Charging suspended by the charger                             |
| `Finishing`     | Session is ending, connector will become available            |
| `Reserved`      | Connector is reserved for a specific user                     |
| `Unavailable`   | Connector is not available (e.g., out of service)             |
| `Faulted`       | Connector has encountered an error                            |

**Detecting Faults:**

To detect faults, check both the `status` and `errorCode` fields in the payload:

* If `status` is `Faulted`, the connector has an active fault
* The `errorCode` field provides details about the fault type (e.g., `GroundFailure`, `OverCurrentFailure`, `PowerMeterFailure`)
* When `errorCode` is `NoError`, the connector is operating normally

**Example - Normal Status Change (Charging):**

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF793",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T11:00:05.000Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL",
      "messageId": "1705317605000",
      "action": "StatusNotification",
      "payload": "{\"connectorId\":1,\"status\":\"Charging\",\"errorCode\":\"NoError\",\"timestamp\":\"2024-01-15T11:00:05.000Z\"}"
    },
    "timestamp": "2024-01-15T11:00:05.000Z"
  }
}
```

**Example - Faulted Connector:**

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF7B0",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T14:22:30.000Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL",
      "messageId": "1705329750000",
      "action": "StatusNotification",
      "payload": "{\"connectorId\":1,\"status\":\"Faulted\",\"errorCode\":\"GroundFailure\",\"info\":\"Ground fault detected on connector\",\"timestamp\":\"2024-01-15T14:22:30.000Z\"}"
    },
    "timestamp": "2024-01-15T14:22:30.000Z"
  }
}
```

**Error Codes (OCPP 1.6):**

| Error Code             | Description                                |
| ---------------------- | ------------------------------------------ |
| `NoError`              | No error to report                         |
| `ConnectorLockFailure` | Failure to lock or unlock connector        |
| `EVCommunicationError` | Communication failure with the vehicle     |
| `GroundFailure`        | Ground fault circuit interrupter activated |
| `HighTemperature`      | Temperature inside Charge Point too high   |
| `InternalError`        | Error in internal hard- or software        |
| `LocalListConflict`    | Conflict with LocalAuthorizationList       |
| `OtherError`           | Other error (see `vendorErrorCode`)        |
| `OverCurrentFailure`   | Over current protection device tripped     |
| `OverVoltage`          | Voltage above acceptable level             |
| `PowerMeterFailure`    | Failure to read power meter                |
| `PowerSwitchFailure`   | Failure to control power switch            |
| `ReaderFailure`        | Failure with idTag reader                  |
| `ResetFailure`         | Unable to perform a reset                  |
| `UnderVoltage`         | Voltage below acceptable level             |
| `WeakSignal`           | Weak wireless signal                       |

#### CALL - RemoteStartTransaction (Nayax Energy Core to Station)

When you initiate a charging session remotely via the API:

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF794",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T12:00:00.000Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL",
      "messageId": "lynk_1705321200000",
      "action": "RemoteStartTransaction",
      "payload": "{\"connectorId\":1,\"idTag\":\"REMOTE_START_TOKEN\"}"
    },
    "timestamp": "2024-01-15T12:00:00.000Z"
  }
}
```

#### CALL\_RESULT - RemoteStartTransaction Response

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF795",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T12:00:00.200Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL_RESULT",
      "messageId": "lynk_1705321200000",
      "payload": "{\"status\":\"Accepted\"}"
    },
    "timestamp": "2024-01-15T12:00:00.200Z"
  }
}
```

#### CALL\_ERROR - Request Rejected

When a station cannot process a request:

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF796",
  "type": "ocpp.message",
  "createdAt": "2024-01-15T12:05:00.000Z",
  "data": {
    "asset": {
      "id": "ast_01ABC123XYZ"
    },
    "connection": {
      "id": "conn_01DEF456UVW",
      "protocol": "ocpp1.6"
    },
    "log": {
      "messageType": "CALL_ERROR",
      "messageId": "lynk_1705321500000",
      "errorCode": "NotSupported",
      "errorDescription": "Requested action is not supported by this charge point",
      "errorDetails": "{}"
    },
    "timestamp": "2024-01-15T12:05:00.000Z"
  }
}
```

### Common Error Codes

When processing `CALL_ERROR` messages, you may encounter these error codes:

| Error Code                     | Description                             |
| ------------------------------ | --------------------------------------- |
| `NotImplemented`               | The requested action is not implemented |
| `NotSupported`                 | The requested action is not supported   |
| `InternalError`                | An internal error occurred              |
| `ProtocolError`                | A protocol error occurred               |
| `SecurityError`                | A security error occurred               |
| `FormationViolation`           | The payload is malformed                |
| `PropertyConstraintViolation`  | A property constraint was violated      |
| `OccurenceConstraintViolation` | An occurrence constraint was violated   |
| `TypeConstraintViolation`      | A type constraint was violated          |
| `GenericError`                 | A generic error occurred                |

***

## asset.connectivity

The `asset.connectivity` event is triggered when a charging station's connection status changes. This allows you to monitor the online/offline status of your charging infrastructure in real-time.

### Connectivity Statuses

The `connectivityStatus` field indicates what happened:

| Status         | Description                                                           |
| -------------- | --------------------------------------------------------------------- |
| `CONNECTED`    | The station has established a WebSocket connection to the OCPP server |
| `DISCONNECTED` | The station has disconnected from the OCPP server                     |

### Connection Lifecycle

```
Station                           Nayax
   │                                │
   │  WebSocket Connect             │
   │ ─────────────────────────────► │
   │                                │  ← CONNECTED event
   │                                │
   │         ... normal operation ...
   │                                │
   │  WebSocket Disconnect          │
   │ ────────────────────────────X  │
   │                                │  ← DISCONNECTED event
```

### Payload Structure

The `data` object in an `asset.connectivity` webhook contains:

| Field                | Type   | Description                                                     |
| -------------------- | ------ | --------------------------------------------------------------- |
| `assetId`            | string | The unique identifier of the charging station                   |
| `timestamp`          | string | ISO 8601 timestamp when the event occurred                      |
| `ocppServerVersion`  | string | The OCPP server version handling this connection (`V1` or `V2`) |
| `connectivityStatus` | string | The connectivity event type: `CONNECTED` or `DISCONNECTED`      |

### Examples

#### Station Connected

When a station first establishes a connection:

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF800",
  "type": "asset.connectivity",
  "createdAt": "2024-01-15T10:29:58.000Z",
  "data": {
    "assetId": "ast_01ABC123XYZ",
    "timestamp": "2024-01-15T10:29:58.000Z",
    "ocppServerVersion": "V1",
    "connectivityStatus": "CONNECTED"
  }
}
```

#### Station Disconnected

When a station loses connection:

```json theme={null}
{
  "id": "whevt_01JGXYZ123ABC456DEF802",
  "type": "asset.connectivity",
  "createdAt": "2024-01-15T18:45:30.000Z",
  "data": {
    "assetId": "ast_01ABC123XYZ",
    "timestamp": "2024-01-15T18:45:30.000Z",
    "ocppServerVersion": "V1",
    "connectivityStatus": "DISCONNECTED"
  }
}
```

### Use Cases

Common use cases for `asset.connectivity` events:

* **Monitoring dashboards** - Display real-time station status
* **Alerting** - Notify operators when stations go offline
* **Analytics** - Track station uptime and reliability metrics
* **Automated diagnostics** - Trigger health checks when stations reconnect