Webhooks

What is a Webhook?

A webhook is a mechanism that allows Fuzz to notify a partner in real-time when a significant event occurs on a site. Concretely, Fuzz sends an HTTP request to an endpoint defined by the partner.

The payload format is defined by Fuzz, and the partner must adapt to this format.

How does it work?

Fuzz allows activating one or more webhooks per site. This is configured through the site configuration in the Fuzz Energy Console. Authentication credentials can also be specified through this configuration if needed.

When an event covered by an active webhook occurs on the site, Fuzz automatically builds and sends the HTTP request to the configured endpoint.

Authentication

Fuzz supports several types of authentication when sending webhook events:

• No authentication: the request is sent without any authentication mechanism.
• Basic Auth: the request includes an Authorization: Basic <credentials> header with Base64-encoded credentials.
• OAuth2 Client Credentials: Fuzz obtains an access token via an OAuth2 Client Credentials flow before sending the request.
• Static Token: the request includes an Authorization: Token <FIX_TOKEN_HERE> header.

HTTP Signature

Regardless of the authentication type, all HTTP requests sent by Fuzz are signed following the RFC 9421 standard. This allows the receiver to verify the integrity and origin of each request.

Example of a signed request

POST /webhook/events HTTP/1.1
Host: partner.example.com
Content-Type: application/json
Content-Length: 342
Date: Sat, 01 Oct 2023 12:00:00 GMT
Authorization: Token abc123secrettoken
Signature-SInput: created=1696176000;keyId="fuzz-edge-key";alg="ed25519";headers="date content-type content-length"
Signature: MEUCIQDX4p6v...signature_value...

{
  "eventId": "3c977fbe-ee7b-4f61-bdd5-035a77e56437",
  "eventType": "ChargePointStatus",
  "siteId": "y1u00tdl",
  "timestamp": "2023-10-01T12:00:00Z",
  "payload": {
    "stationId": "jvpfa6ie",
    "chargePointId": "1sjn7tza",
    "connectorId": 1,
    "status": "Charging",
    "errorCode": "NoError"
  }
}

The Signature-Input header declares:

• created: timestamp when the signature was generated.
• keyId: identifier of the signing key, shared out-of-band with the partner.
• alg: signing algorithm (e.g., ed25519, rsa-pss-sha512).
• headers: list of HTTP headers included in the signature calculation.

The Signature header carries the actual cryptographic signature over the selected headers and the request body.

General Event Format

All webhooks follow the same envelope structure:

{
  "eventId": "3c977fbe-ee7b-4f61-bdd5-035a77e56437",
  "eventType": "ChargePointStatus",
  "siteId": "site123",
  "timestamp": "2023-10-01T12:00:00Z",
  "payload": {
    "...": "..."
  }
}

Field	Type	Description
eventId	string	The unique identifier of the event (UUID).
eventType	string	The type of event. See the list below.
siteId	string	The unique identifier of the site where the station is located, as defined in the Fuzz system.
timestamp	date	The date and time the event was sent (ISO 8601 format, Europe/Brussels timezone).
payload	object	Event-specific content. The structure varies depending on the eventType.

Event Types

Fuzz supports the following event types:

eventType	Description
Authorize	Triggered when a charge authorization request is processed.
ChargePointStatus	Triggered when the status of a charge point changes.
StartTransaction	Triggered when a charging transaction starts.
StopTransaction	Triggered when a charging transaction stops.

Each event type has a specific payload whose structure is detailed on the dedicated pages.