Webhooks

Get told when a session finishes, instead of polling for it.

Register a URL with Set Fleet Webhook and LotGrids POSTs to it once a session your fleet started (via Start Charge Session) finishes. No webhook, no calls — it's entirely optional.

Events

EventFires when
charge.completedThe session dispensed its full confirmed amount.
charge.interruptedThe charger stopped early — actualDispensedValue will be less than confirmedAmount, and the difference was already refunded to the driver's sub-wallet before this fires.
charge.quotedAn on-site operator sent a price for a manual charger's session that was waiting on one — see Quote Charge Session and Confirm Session Payment.

Payload

POST <your webhookUrl>
Content-Type: application/json
X-LotGrids-Signature: sha256=5f8a2c...

{
  "event": "charge.completed",
  "sessionId": "8f3c1a...",
  "chargerId": "chg_04af1c",
  "connectorId": "conn_02",
  "driverEmail": "adaeze.driver@fleetco.com",
  "confirmedAmount": 12000,
  "actualDispensedValue": 12000,
  "refundAmount": 0,
  "timestamp": "2026-09-22T14:03:11.482Z"
}

charge.quoted has a different shape — no confirmedAmount/actualDispensedValue yet, since nothing's been paid for:

POST <your webhookUrl>
Content-Type: application/json
X-LotGrids-Signature: sha256=91ab3f...

{
  "event": "charge.quoted",
  "sessionId": "sess_9f3ac2e1",
  "chargerId": "chg_04af1c",
  "connectorId": "conn_02",
  "driverEmail": "adaeze.driver@fleetco.com",
  "quotedAmount": 7500,
  "pricePerKwh": 500,
  "kwhNeeded": 15,
  "timestamp": "2026-09-22T14:05:02.118Z"
}

The session this refers to expires 5 minutes after this fires — call Confirm Session Payment promptly.

Verifying a delivery

X-LotGrids-Signature is an HMAC-SHA256 of the raw request body, using the webhookSecret Set Fleet Webhook returned. Recompute it and compare — don't just check the header is present.

const crypto = require('crypto');

function isValidSignature(rawBody, signatureHeader, webhookSecret) {
  const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
  const provided = (signatureHeader || '').replace(/^sha256=/, '');
  return provided.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(provided), Buffer.from(expected));
}

Use the raw, unparsed request body for this — re-serializing a parsed JSON object won't byte-for-byte match what was signed.

Delivery

Best-effort: a single POST attempt, no retries. Respond with any 2xx status quickly — LotGrids doesn't wait on your processing, only on the HTTP response.

Sandbox sessions complete instantly server-side (there's no real hardware to wait on), so a test-key session's webhook is deliberately delayed ~60 seconds rather than firing the moment you call Start Charge Session — matching how long the LotGrids map app's own demo keeps its "charging" screen up. A live-key session's webhook fires as soon as the charger actually reports completion, with no added delay.