StopTransaction Webhook

Description

The StopTransaction webhook is triggered whenever a charging transaction ends on a Fuzz-managed station.

This webhook is fired in two scenarios:

1. OCPP: When a charging station stops a transaction - whether due to the vehicle disconnecting, a remote stop command, an emergency stop, or another reason - it sends a StopTransaction message via OCPP. Fuzz processes this message and fires this webhook event on the Post-Stop Transaction hook to notify your system that a charging session has concluded.
2. Modbus: When Fuzz detects the end of a charging transaction via Modbus (by monitoring meter readings and current draw from electrical assets connected via Modbus TCP/RTU), it will also trigger this webhook to notify your system.

In both cases, the payload structure and delivery mechanism are identical.

Payload Structure

The webhook uses the standard Fuzz envelope with a StopTransaction-specific payload:

{
  "eventId": "3c977fbe-ee7b-4f61-bdd5-035a77e56437",
  "eventType": "StopTransaction",
  "siteId": "y1u00tdl",
  "timestamp": "2023-10-01T12:00:00+02:00",
  "payload": {
    "stationId": "jvpfa6ie",
    "chargePointId": "1sjn7tza",
    "connectorId": 1,
    "idTag": "12345",
    "meterStart": 156.45,
    "meterStop": 159.92,
    "transactionId": 123,
    "reason": "EVDisconnected"
  }
}

Envelope Fields

Field	Type	Description
eventId	string	Unique identifier of the webhook event (UUID).
eventType	string	Always "StopTransaction" for this event type.
siteId	string	The unique identifier of the site where the station is located.
timestamp	string	ISO 8601 timestamp in the Europe/Brussels timezone.

Payload Fields

Field	Type	Required	Description
stationId	string	Yes	The unique identifier of the station where the transaction ended.
chargePointId	string	Yes	The identifier of the charge point on which the transaction ended.
connectorId	integer	Yes	The connector ID on the charge point.
idTag	string	Yes	The identification tag used for the transaction (e.g., RFID card number, vehicle certificate ID).
meterStart	number	Yes	The meter reading in kWh at the start of the transaction.
meterStop	number	Yes	The meter reading in kWh at the end of the transaction.
transactionId	integer	Yes	The unique identifier of the transaction, assigned by the charge point.
reason	string	No	The reason why the transaction was stopped. May only be omitted when the reason is "Local". See the Reason Values table below.

Reason Values

Reason	Description
Local	The transaction was stopped locally at the charge point (e.g., driver unplugged).
EVDisconnected	The vehicle was disconnected from the connector.
EmergencyStop	An emergency stop was triggered at the charge point.
Remote	The transaction was stopped via a remote command from the CPO.
HardReset	A hard reset of the charge point caused the transaction to stop.
SoftReset	A soft reset of the charge point caused the transaction to stop.
Reboot	The charge point rebooted, causing the transaction to stop.
PowerLoss	A power loss event caused the transaction to stop.
UnlockCommand	An unlock command was issued, causing the transaction to stop.
DeAuthorized	The idTag was de-authorized during the transaction.
Other	An unspecified reason caused the transaction to stop.

Retry Mechanism

Fuzz implements a robust queue-based delivery system for webhook events to ensure reliable notification:

Queue Processing

• Each webhook type maintains a dedicated background thread that processes events from a bounded queue (capacity: 1000 messages).
• When a stop transaction event occurs, it is enqueued and processed asynchronously by the dedicated thread.
• If the webhook is disabled for a site, the thread is gracefully interrupted.

Retry Policy

• For each HTTP request, Fuzz applies a fixed-delay retry strategy:
  • Up to 360 retry attempts with a 10-second interval between retries.
  • This provides a maximum retry window of approximately 60 minutes per request.
• If all retry attempts fail, the error is logged with the Webhook_SendHttp exception type and the event is discarded to prevent queue buildup.

Health Monitoring

The webhook executor exposes health metrics for monitoring:

• Last queue consumption: Timestamp of the last dequeued message.
• Queue size: Current number of pending messages (alerts if > 5, critical if > 100).
• Last webhook request: Timestamp and duration of the last HTTP request (alerts if > 500ms, critical if > 5000ms).

Example HTTP Request

Below is an example of a signed HTTP request sent by Fuzz for a StopTransaction webhook:

POST /webhook/events HTTP/1.1
Host: partner.example.com
Content-Type: application/json
Content-Length: 468
x-request-id: 3c977fbe-ee7b-4f61-bdd5-035a77e56437
Signature-Input: sig1=created=1696176000;keyId="webhook";alg="rsa-pss-sha256";headers="@method @path x-request-id"
Signature: MEUCIQDX4p6vK8fN2mR7sT1uV3wX5yZ0aBcDeFgHiJkLmNoPqRsTuVw

{
  "eventId": "3c977fbe-ee7b-4f61-bdd5-035a77e56437",
  "eventType": "StopTransaction",
  "siteId": "site123",
  "timestamp": "2023-10-01T12:00:00+02:00",
  "payload": {
    "stationId": "station456",
    "chargePointId": "cp789",
    "connectorId": 1,
    "idTag": "12345",
    "meterStart": 156.45,
    "meterStop": 159.92,
    "transactionId": 123,
    "reason": "EVDisconnected"
  }
}

Signature Headers

All requests are signed following the RFC 9421 standard:

Header	Description
x-request-id	Unique identifier for the request, generated as a UUID.
Signature-Input	Declares the signature parameters: created timestamp, keyId identifier, signing algorithm (alg), and the list of HTTP components included in the signature (@method, @path, x-request-id).
Signature	The cryptographic signature over the declared components, generated using the Fuzz edge keystore.

Verifying the Signature

The public key used to verify webhook signatures is available via the JWKS endpoint:

https://auth.fuzz.energy/.well-known/jwks.json

Use the key with kid: "sign" to validate the signature. This allows you to cryptographically verify that each webhook request originates from Fuzz and has not been tampered with in transit.