Authorize Webhook

Description

The Authorize webhook is triggered whenever an OCPP Authorize request is processed by the Fuzz Local Controller.

When a charging station receives an identification tag (e.g., via RFID card, Plug & Charge, or manual entry), it sends an Authorize request to the Fuzz edge controller. After the authorization decision is made - whether locally, via a plugin, or by forwarding to a CPO - Fuzz sends this webhook event to notify your system of the result.

This webhook fires in two scenarios:

• Post-Authorize: After the CPO responds to an authorization request forwarded by Fuzz.
• Post-Start Charging: When a transaction starts and the authorization status is re-evaluated.

Payload Structure

The webhook uses the standard Fuzz envelope with an Authorize-specific payload:

{
  "eventId": "3c977fbe-ee7b-4f61-bdd5-035a77e56437",
  "eventType": "Authorize",
  "siteId": "y1u00tdl",
  "timestamp": "2023-10-01T12:00:00+02:00",
  "payload": {
    "stationId": "jvpfa6ie",
    "idTag": "12345",
    "status": "Accepted",
    "chargePointId": "1sjn7tza",
    "connectorId": 1
  }
}

Envelope Fields

Field	Type	Description
eventId	string	Unique identifier of the webhook event (UUID).
eventType	string	Always "Authorize" 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 that processed the authorization.
idTag	string	Yes	The identification tag presented by the EV driver (e.g., RFID card number, vehicle certificate ID).
status	string	Yes	The authorization status. Possible values: Accepted, Blocked, Expired, Invalid, ConcurrentTx.
chargePointId	string	No	The identifier of the charge point associated with the authorization.
connectorId	integer	No	The connector ID on which the transaction is associated. Present when a transaction is already in progress.

Status Values

Status	Description
Accepted	The idTag was accepted and the EV driver is authorized to charge.
Blocked	The idTag is blocked and cannot be used for charging.
Expired	The idTag has expired and is no longer valid.
Invalid	The idTag is not recognized or is malformed.
ConcurrentTx	The idTag already has an active transaction and cannot start another.

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 an authorization 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 an Authorize webhook:

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

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.