Webhooks

A webhook destination sends one HTTP request to your endpoint each time a chosen event happens — for example a charger finishing a transaction or a roaming partner sending a CDR. You manage destinations in the Dashboard under Observability → Callbacks (/dashboard/webhooks).

Never paste live OCPP passwords, OCPI tokens, or client certificates into tickets, chat, or public issues. Rotate anything that may have been exposed and use Dashboard or your secret store for operational credentials.

Events

Each destination listens to exactly one event. Create one destination per event you need.

Events are scoped to your organization: a destination never receives another organization's events.

Create a destination

1. Prepare your endpoint

   Expose an HTTPS URL that accepts the request and returns 2xx before doing any slow work. Requests time out after the destination's timeout (1,000–10,000 ms, default 5,000 ms).

2. Add the destination

   Open Observability → Callbacks and select Add destination. Fill in:

   • Name — no spaces, for example billing_stop_transaction
   • Event — one event from the table above
   • Method and URL — POST (sends a JSON body) or GET; the URL must start with http:// or https://
   • Timeout — 1,000–10,000 ms
   • HTTP headers and HTTP parameters — optional, sent with every request
3. Authenticate the request

   OCPPLab does not sign webhook requests. Add a secret header (for example Authorization: Bearer <random value>) under HTTP headers, and reject requests on your side that do not carry it.

   webhook-handler.ts

   1// Check the shared secret you set as a destination header, then respond fast.
   2export async function POST(req: Request) {
   3  if (req.headers.get("authorization") !== `Bearer ${process.env.OCPPLAB_WEBHOOK_SECRET}`) {
   4    return new Response("unauthorized", { status: 401 })
   5  }
   6  const event = await req.json()
   7  await queue.enqueue(event) // process after responding
   8  return new Response(null, { status: 204 })
   9}

4. Check the first delivery

   Trigger the event (for example start and stop a session on a virtual charger), then open Webhook logs and confirm a 2xx row for your URL.

Result: the destination is Active in the Callbacks list, and its error rate reflects real deliveries.

Callbacks — enable, disable, edit, or delete a destination from its row menu. View logs opens its deliveries.

Request format

POST requests carry Content-Type: application/json unless you set another content type. The body is the event payload from the producer. When an event has no payload, OCPPLab sends this envelope:

1{
2  "type": "ev_cloud.webhook.event",
3  "event_type": "stop_transaction",
4  "table": null,
5  "op": null,
6  "subscription_id": 42,
7  "organization_id": "4b0c3c9e-…",
8  "sent_at": "2026-10-01T16:23:05.000Z"
9}

GET requests send no body; use HTTP parameters to pass values in the query string.

Delivery behavior

• One attempt per event. A failed or timed-out delivery is recorded but not retried. Make your endpoint available, and reconcile from the Dashboard or API if you miss events.
• Logged both ways. Every attempt appears in Webhook logs (/dashboard/webhooks/logs) with its HTTP status, duration, and error, such as Timed out after 5000ms or network_error.
• Error rate. The Callbacks list shows each destination's error rate over its deliveries, or — when it has none yet.

Webhook logs — red bars and 5xx rows are failed deliveries.

Troubleshooting

Related

• Observability — Callbacks and Webhook logs in the Dashboard
• Architecture — how events leave the data plane