Web hook authorization

Use webhooks to authorize charging sessions with your backend and receive completed session data for logging and billing.

What is a webhook?

A webhook is an HTTP callback that lets Zaptec Cloud notify an external system when specific events occur.

Instead of polling Zaptec APIs for changes, your system exposes a URL and Zaptec Cloud sends an HTTP POST request whenever the configured event occurs.

Zaptec Cloud currently supports webhooks for:

• Session start — authorization decisions before charging starts
• Session end — delivery of completed session data for logging and billing

Prerequisites

1. Configure the installation to use web hook authorization on the installation details page.
2. Expose your web hooks over HTTPS.
3. Require authentication for production web hooks using either:
   • OAuth 2.0 bearer tokens, or
   • HTTP Basic authentication
4. Accept and return application/json for all web hook requests and responses.

Webhook authorization overview

Zaptec Cloud calls your HTTP endpoints during the charging process using HTTP POST.

• The charge session starts only if your external provider authorizes the request.
• All webhooks must use Content-Type: application/json.
• All webhooks should return the JSON payload documented for that hook.

When an installation is configured to use webhook authorization, Zaptec Cloud calls your webhooks as part of the normal charging flow:

1. A vehicle is connected to a charging station.
2. Zaptec Cloud calls your Session start webhook.
3. Your system decides if charging is allowed and, if approved, returns a unique sessionId.
4. When the vehicle disconnects, Zaptec Cloud calls your Session end webhook with the final session data.
5. Your system can use this data for logging and invoicing.

sequenceDiagram
    participant EV as Vehicle
    participant CS as Charging station
    participant ZC as Zaptec Cloud
    participant SStart as Session start webhook
    participant SEnd as Session end webhook

    EV->>CS: Connect cable / scan RFID
    CS->>ZC: Vehicle connected

    loop Every 10s until authorized, timeout, or disconnect
        ZC->>SStart: POST SessionStart with token, chargerId, installationId
        alt Authorized
            SStart-->>ZC: 200 OK with sessionId
            ZC->>CS: Allow charging
            CS->>EV: Start charging
        else Unauthorized (401)
            SStart-->>ZC: 401 Unauthorized
        else Error (400+ except 401)
            SStart-->>ZC: Error
            ZC->>CS: Deny charging
        end
    end

    CS->>EV: Start charging

    EV->>CS: Disconnect cable
    CS->>ZC: Session completed

    ZC->>SEnd: POST SessionEnd with sessionId, sessionStart, sessionEnd, energy
    alt Success
        SEnd-->>ZC: 200 OK
    else Failure (400+)
        SEnd-->>ZC: Error
        note over ZC: Retry SessionEnd until success or timeout
    end

Configuration

Webhook configuration is available on the installation details page when the installation is set to use webhook authorization.

The following configuration options are available.

Authentication URL

Use this URL to obtain a bearer token before ZapCloud calls your web hooks.

If this URL is set:

• ZapCloud posts the authentication payload to this URL.
• The request uses:
  • Content-Type: application/x-www-form-urlencoded
• Your token service returns an access_token.
• ZapCloud then calls the web hook with:

Authorization: Bearer {access_token}

If this URL is not set:

• ZapCloud uses the username and password from the authentication payload for HTTP Basic authentication when calling the web hooks.
• The payload must be a query string:

username={username}&password={password}

Authentication payload

This is the exact form body ZapCloud posts to the Authentication URL to obtain an OAuth token.

It must match the format expected by your token service.

Example:

grant_type=password&username={username}&password={password}

Session start URL

ZapCloud calls this URL before a session is allowed to start.

If external authorization is enabled but this URL is omitted, ZapCloud falls back to internal authorization.

Session end URL

ZapCloud calls this URL after the charging session is complete and the vehicle is disconnected.

Web hook requirements

All web hooks:

• are called with HTTP POST
• use application/json request and response bodies

Any HTTP status code other than these results in an immediate denial of charging and stops the authorization process:

• 200 OK — authorized or successful
• 401 Unauthorized — retryable authorization failure

Session start web hook

Use the session start web hook to decide whether a user may begin charging.

When ZapCloud calls it

ZapCloud calls the session start web hook when:

1. a user connects an EV to a charging station
2. optionally, an RFID token is scanned

The request includes:

• charger information
• installation identity
• optionally, an RFID token code

What your system must do

Your system must:

1. Identify the user by using one of these methods:
   • the provided RFID token
   • a charger-to-customer mapping
   • another method such as your app, SMS flow, or backend user lookup
2. Decide whether charging is allowed.
3. If charging is allowed:
   • create a unique UUID session identifier
   • return it in the JSON response
   • return 200 OK
4. If charging is not allowed:
   • return 401 Unauthorized
5. If another failure occurs:
   • return an appropriate error code (>= 400)

Request format

Zaptec Cloud sends a POST request to the configured Session start URL:

POST /api/zaptec/session-start HTTP/1.1
Host: partner.example.com
Authorization: Bearer {access_token-or-Basic}
Content-Type: application/json

{
  "token": "04AABBCCDD",
  "chargerId": "b7f0c79c-0a76-4b87-a469-90d91e3ac901",
  "chargerName": "P1 – Basement spot 12",
  "installationId": "4adc8954-274b-4acd-a2e3-3a31567565e9",
  "installationName": "Office Garage A"
}

Field notes

Response scenarios

Authorized

If the request is authorized, the webhook must return 200 OK and a unique session identifier:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "sessionId": "b92a3549-5a36-4fab-b5c3-12e84a89c517"
}

sessionId must be a UUID string. This value is used by Zaptec Cloud to track the session and is included in the Session end webhook.

Not authorized (retryable)

If the request should not be authorized, return 401 Unauthorized:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "authorization_required",
  "error_description": "Unknown RFID token or user not allowed on this charger."
}

Error (non-retryable for this session)

Any status code >= 400 other than 401 is treated as an error and immediately denies charging:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "internal_error",
  "error_description": "Payment backend unavailable."
}

Polling behavior

If your web hook keeps returning 401 Unauthorized, ZapCloud polls the session start web hook every 10 seconds.

ZapCloud stops polling when one of these happens:

• the first failed authorization attempt with an RFID token is recorded
• the 5-minute polling timeout elapses
• the charger is disconnected from the vehicle

RFID behavior

If RFID is required:

• the driver must scan the RFID token after connecting the vehicle
• until a token is scanned, requests arrive without a token code
• your web hook should continue returning 401 Unauthorized until the token is present so ZapCloud can retry

User feedback

The charger has no display. The only built-in status indicator is the LED Z-logo.

• failed authorization is indicated by the Z-logo flashing red
• if you need user-facing error details, show them in your own app or UI
• your web hook can still return an error message for Zaptec logging and debugging

Session end web hook

Use the session end web hook to receive session data for billing, logging, or analytics.

When ZapCloud calls it

ZapCloud calls the session end web hook:

• after the charge session is complete
• after the vehicle is disconnected
• after the session is already closed in Zaptec’s database

Payload fields

Request format

Zaptec Cloud sends a POST request to the configured Session end URL:

POST /api/zaptec/session-end HTTP/1.1
Host: partner.example.com
Authorization: Bearer {access_token-or-Basic}
Content-Type: application/json

{
  "sessionId": "b92a3549-5a36-4fab-b5c3-12e84a89c517",
  "sessionStart": "2026-05-01T11:02:15Z",
  "sessionEnd": "2026-05-01T13:37:48Z",
  "energy": 18.42
}

Session end timing note

The session ends when the vehicle is disconnected, not necessarily when the battery first reaches full charge.

For example, the vehicle may request more power later for cabin or battery heating.

Response scenarios

Success

For successful processing, return 200 OK:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok"
}

Zaptec Cloud logs the response but only relies on the HTTP status code.

Failure and retries

If your system cannot process the session, return an error status such as 500:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "status": "error",
  "error": "db_timeout",
  "error_description": "Session could not be persisted. Please retry."
}

Retries and error handling

If the session end web hook call fails, ZapCloud retries it periodically until success or timeout.

You can also query session status and details through the ZapCloud API using Session_Get and the sessionId.

If your web hook fails:

• return the correct HTTP status code
• include a detailed error message to help Zaptec troubleshoot the problem

Payment solution using web hooks

You can use web hooks to build a payment or invoicing flow.

Actors

• Zaptec / ZapCloud
• 3rd-party backend
• customers

Prerequisites

Your system must maintain one of these mappings:

• Zaptec charger ID → customer
• RFID token / idTag → customer

Billing flow

1. ZapCloud calls the session start web hook with:
   • charger ID
   • installation ID
   • optional token
2. Your backend:
   • identifies the customer
   • authorizes the request
   • returns a UUID sessionId if authorized
3. ZapCloud calls the session end web hook with:
   • sessionId
   • session start time
   • session end time
   • energy consumed
4. Your backend:
   • looks up the customer
   • computes billing using the session data
   • performs invoicing or stores the session for later processing

Mermaid diagrams

Session start communication flow

sequenceDiagram
    participant EV as Vehicle
    participant CS as Charging station
    participant ZC as ZapCloud
    participant WH as Session start webhook (3rd party)

    EV->>CS: Connect cable
    CS->>ZC: Vehicle connected
    ZC->>WH: POST /SessionStart (charger & installation info,<br/>optional RFID)
    alt Authorized (HTTP 200)
        WH-->>ZC: 200 OK + sessionId (UUID)
        ZC->>CS: Allow charging
        CS->>EV: Start charging
    else Unauthorized (HTTP 401)
        WH-->>ZC: 401 Unauthorized
        note over ZC: Poll every 10s<br/>until RFID scanned / timeout / disconnect
        ZC-->>WH: Retry POST /SessionStart
    else Error (>=400, not 401)
        WH-->>ZC: Error (e.g. 500)
        ZC->>CS: Deny charging
        CS->>EV: Charging not started<br/>(LED flashes red)
    end

Session end communication flow

sequenceDiagram
    participant EV as Vehicle
    participant CS as Charging station
    participant ZC as ZapCloud
    participant WH as Session end webhook (3rd party)

    EV->>CS: Disconnect cable
    CS->>ZC: Session complete
    ZC->>ZC: Close session in DB
    ZC->>WH: POST /SessionEnd<br/>{ sessionId, sessionStart,<br/>sessionEnd, energy }
    alt Success (HTTP 200)
        WH-->>ZC: 200 OK
        note over WH: Use data for billing / logging
    else Failure (>=400)
        WH-->>ZC: Error (status & message)
        note over ZC: Retry periodically<br/>until success or timeout
    end

Web hook-based payment flow

flowchart LR
    subgraph Zaptec
        Z1[Charging station]
        Z2[ZapCloud<br/>Session management]
    end

    subgraph Partner[Third-party backend]
        M[Mapping token or charger to customer]
        L[Session logging and billing]
    end

    Z1 -->|Vehicle connects / RFID| Z2
    Z2 -->|POST SessionStart<br/>token, chargerId, installationId| L
    L -->|Lookup| M
    M --> L
    L -->|200 with sessionId| Z2
    Z2 -->|Allow charging| Z1

    Z1 -->|Vehicle disconnects| Z2
    Z2 -->|POST SessionEnd<br/>sessionId, times, energy| L
    L -->|Create invoice / update accounts| M

Recommended implementation checklist

Before going live:

• require authentication on all production web hooks
• serve all web hooks over HTTPS
• validate Content-Type
• return the correct HTTP status codes
• generate a UUID sessionId for authorized sessions
• support retry-safe handling for repeated 401 polling and session end retries
• log incoming requests and outgoing responses for debugging