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
| Event | Fires when |
|---|---|
charge.completed | The session dispensed its full confirmed amount. |
charge.interrupted | The 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.quoted | An 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.