StartTransaction Webhook

Description

The StartTransaction webhook is triggered whenever a new charging transaction begins on a Fuzz-managed station.

This webhook is fired in two scenarios:

1. OCPP: When a charging station starts a transaction - after successful authorization of an idTag - it sends a StartTransaction message via OCPP. Fuzz processes this message and fires this webhook event on the Post-Start Transaction hook to notify your system that a charging session has begun.
2. Modbus: When Fuzz detects the start 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 StartTransaction-specific payload:

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

Envelope Fields

Field	Type	Description
eventId	string	Unique identifier of the webhook event (UUID).
eventType	string	Always "StartTransaction" 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 started.
chargePointId	string	Yes	The identifier of the charge point on which the transaction started.
connectorId	integer	Yes	The connector ID on the charge point.
idTag	string	Yes	The identification tag used to start the transaction (e.g., RFID card number, vehicle certificate ID).
meterStart	number	Yes	The meter reading in kWh at the start of the transaction.
transactionId	integer	Yes	The unique identifier of the transaction, assigned by the charge point.
reservationId	string	No	The reservation ID if the transaction was initiated from a prior reservation.

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 start 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 StartTransaction webhook:

POST /webhook/events HTTP/1.1
Host: partner.example.com
Content-Type: application/json
Content-Length: 445
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": "StartTransaction",
  "siteId": "y1u00tdl",
  "timestamp": "2023-10-01T12:00:00+02:00",
  "payload": {
    "stationId": "jvpfa6ie",
    "chargePointId": "1sjn7tza",
    "connectorId": 1,
    "idTag": "12345",
    "meterStart": 156.45,
    "transactionId": 123,
    "reservationId": "resv123"
  }
}

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.