Webhooks

Often something will happen in Axle’s system that you want to know about in your own system. For example, a user might finish onboarding and become eligible for dispatch. You can receive these events in real time via webhooks. Messages are delivered at-least-once, and may arrive out of order, so your handler should be idempotent and sequence on created_at if order matters.

Registering your endpoint

We send you messages at a URL you provide, with one URL per environment, and a signing secret which you can use to verify that the message came from Axle. To register your endpoint you can get in touch and provide the URL and secret for the events you want to receive. If you want different events to go to different endpoints we can do that too. We’ll first implement the webhook in the sandbox environment and once you’ve signed the integration off we’ll move it to production. You can change the URL or secret at any time, and we’ll start sending events to the new URL, and rotate the secret for you. Your endpoint only needs to accept HTTP POST requests with a JSON body, and return a 2xx response once the event is durably accepted.

Events

Event type	Fires when
`user:onboarding:complete`	A user finishes onboarding: enrolled, consented, and eligible for dispatch.
`asset:dispatch:requested`	A market dispatch is scheduled for one of your assets and we need you to execute it over the window.
`vpp:asset:registered`	A battery is registered on the Axle VPP through Axle’s signup flow, and we hand you the identifiers for it.
`vpp:dispatch:requested`	A VPP grid event is scheduled and we need you to hold a target power on each affected battery over the window.

The vpp: events are for battery fleets on the Axle VPP, and carry a power setpoint in kW. asset:dispatch:requested is for EV charging, and carries a coarse action rather than a setpoint. An integration normally receives one family or the other, not both.

The envelope

Every event shares the same envelope, with the event-specific fields in payload, sent as Content-Type: application/json. We’ve formatted the example below for readability; on the wire it’s compact JSON, which matters once you get to verifying the signature.

{
  "id": "0198f0a1-2b3c-7d4e-8f90-1a2b3c4d5e6f",
  "version": "v0.0.0",
  "event_type": "user:onboarding:complete",
  "created_at": "2026-08-11T14:02:11.482913Z",
  "payload": {
    "site_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8",
    "completed_at": "2026-08-11T14:02:11.301045Z",
    "external_user_id": "1234567"
  }
}

Field order isn’t part of the contract, so parse the JSON rather than matching on it. It is stable for a given event, including across retries, but don’t rely on it matching the order documented here.

Field	Type	Description
`id`	string (UUID)	Unique identifier for this event. Stable across retries, so use it to deduplicate.
`version`	string	Envelope version, set per event type. The `vpp:` events are at `v1.0.0`; the others stay at `v0.0.0` while their contracts settle.
`event_type`	string	Which event this is, from the table above.
`created_at`	string (ISO 8601, UTC)	When Axle recorded the event, which can be earlier than when we sent it. A retried event keeps its original `created_at`.
`payload`	object	Event-specific fields.

Event payloads

The payload object contains the fields specific to the event type. The fields are stable for a given event, including across retries, but don’t rely on them matching the order documented here. Field names aren’t shared across event types, so read the table for the event you’re handling rather than assuming a name carries over from another one.

`user:onboarding:complete`

Field	Type	Description
`payload.site_id`	string (UUID)	The Axle site identifier for this user.
`payload.external_user_id`	string	Your own identifier for the user, as supplied when the site was created.
`payload.completed_at`	string (ISO 8601, UTC)	When the user finished onboarding.

`asset:dispatch:requested`

Asks you to drive an asset to a setpoint over a window. The event is sent when the dispatch is scheduled, which can be ahead of from_dt, so don’t act on it until the window opens. Return a 2xx if you will execute the dispatch, and a 4xx if you can’t: the asset is unknown, the window is invalid, or the asset is offline, for example.

Field	Type	Description
`payload.asset_id`	string (UUID)	The Axle asset identifier for the asset being dispatched.
`payload.action`	string	What to do with the asset over the window, from the table below.
`payload.from_dt`	string (ISO 8601, UTC)	Start of the dispatch window.
`payload.to_dt`	string (ISO 8601, UTC)	End of the dispatch window.

Action	Meaning
`pause_consumption`	Drive the asset’s consumption to 0% of its rated power for the window.
`max_consumption`	Drive the asset’s consumption to 100% of its rated power for the window.

We may add actions over time, so return a 4xx for any action you don’t recognise.

`vpp:asset:registered`

Fires when a customer finishes signup on Axle’s hosted VPP flow and we create the battery asset. It carries the identifiers you need for telemetry and dispatch, along with your own device serial so you can match the asset to your customer. Return a 2xx once you’ve recorded the asset, and a 4xx only for a genuine refusal, such as a device serial you don’t recognise.

Field	Type	Description
`payload.site_id`	string (UUID)	The Axle site identifier for the customer.
`payload.asset_id`	string (UUID)	The Axle asset identifier for the battery. Use this for telemetry and dispatch.
`payload.device_serial`	string	The device serial as returned by your own device-list API, so you can match the asset to your customer.
`payload.registered_at`	string (ISO 8601, UTC)	When Axle created the asset.

{
  "id": "0198f0b2-3c4d-7e5f-8a01-2b3c4d5e6f70",
  "version": "v1.0.0",
  "event_type": "vpp:asset:registered",
  "created_at": "2026-08-11T14:02:11.482913Z",
  "payload": {
    "site_id": "9f2b7a13-4c8d-4e21-9a76-5d1c3b8e0f42",
    "asset_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8",
    "device_serial": "OEM-SERIAL-12345",
    "registered_at": "2026-08-11T14:02:11.301045Z"
  }
}

See Axle VPP integration for where this sits in the wider signup flow.

`vpp:dispatch:requested`

Asks you to hold a target power at each battery’s inverter over a window. One event covers every asset affected by a single grid event, so you get one delivery per event rather than one per battery. We give you at least 30 minutes’ notice before an event, normally 4 hours to a day ahead. The event is sent when the dispatch is scheduled, so don’t act on it until start_time.

Field	Type	Description
`payload.event_id`	string (UUID)	Identifier for the grid event itself, shared by every asset in this instruction. Distinct from the envelope `id`, which identifies this delivery.
`payload.issued_timestamp`	string (ISO 8601, UTC)	When Axle issued the instruction.
`payload.start_time`	string (ISO 8601, UTC)	Start of the dispatch window.
`payload.end_time`	string (ISO 8601, UTC)	End of the dispatch window.
`payload.assets`	array	One entry per affected asset.
`payload.assets[].asset_id`	string (UUID)	The Axle asset identifier, as supplied at registration.
`payload.assets[].power_kw`	number	Target power for the asset across the window, applied at the inverter. Positive = charge (import into the battery), negative = discharge (export).

{
  "id": "0198f0c3-4d5e-7f60-9b12-3c4d5e6f7081",
  "version": "v1.0.0",
  "event_type": "vpp:dispatch:requested",
  "created_at": "2026-06-29T17:02:37.512804Z",
  "payload": {
    "event_id": "eab8c867-7c4d-4116-a587-02c9d1f13a16",
    "issued_timestamp": "2026-06-29T17:02:37.448917+00:00",
    "start_time": "2026-06-30T20:30:00+00:00",
    "end_time": "2026-06-30T21:30:00+00:00",
    "assets": [
      { "asset_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8", "power_kw": -6.915 },
      { "asset_id": "1a161164-5187-4b4b-8e8a-7b3f67c4d5a8", "power_kw": -4.915 }
    ]
  }
}

This event is batched, so a 4xx refuses the whole instruction and we won’t retry any part of it. If you don’t recognise one asset_id, skip that entry and still return a 2xx. Return a 5xx only if you can’t accept the instruction at all.

Deduplicate on the envelope id as you would for any other event. Because the instruction is batched, that covers every asset in the event in one go.

power_kw is the target at the inverter. We normally dispatch at the inverter’s maximum power rating, and account for household load potentially limiting the power the battery delivers.

We may add fields to a payload without changing version, so ignore anything you don’t recognise rather than rejecting the request. We’ll version the envelope before we make a breaking change.

Verifying the signature

Every request carries two headers:

Header	Description
`x-axle-sig`	`t=<unix timestamp>,v1=<hex HMAC-SHA256>`. We cover the timestamp in the signature, so a captured request can’t be replayed indefinitely.
`x-axle-ref`	The envelope `id`, for correlation in your logs. Not signed, so don’t rely on it for anything security-sensitive.

Verify in four steps; both samples below do all of them.

Take the raw request body

Verify against the exact bytes we sent. Parsing the JSON and re-serialising it will change the signature.

Parse x-axle-sig into its fields

Split on ,, then on the first =. Ignore fields you don’t recognise; we may add a second signature scheme (v2=...) alongside v1 before retiring it.

Reject stale timestamps

Discard the request if t is more than 300 seconds from your clock. This is what bounds the replay window.

Recompute and compare

Compute the hex HMAC-SHA256 of "{t}.{body}", keyed by your signing secret, and compare it to v1 in constant time. Use the secret exactly as we gave it to you, as a UTF-8 string, without decoding it first.

Python
Node.js

import hashlib
import hmac

TOLERANCE_SEC = 300


def verify(secret: str, body: str, signature_header: str, received_at_ts: int) -> bool:
    fields = dict(f.split("=", 1) for f in signature_header.split(",") if "=" in f)
    timestamp, signature = fields.get("t"), fields.get("v1")
    # isdigit() alone accepts non-ASCII digits that int() then rejects, so check both
    if not timestamp or not signature or not (timestamp.isascii() and timestamp.isdigit()):
        return False

    if abs(received_at_ts - int(timestamp)) > TOLERANCE_SEC:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
    # compare as bytes: compare_digest rejects str containing non-ASCII
    return hmac.compare_digest(expected.encode(), signature.encode())

const crypto = require("crypto");

const TOLERANCE_SEC = 300;

function verify(secret, body, signatureHeader, receivedAtTs) {
  const fields = Object.fromEntries(
    signatureHeader.split(",").map((field) => {
      const i = field.indexOf("=");
      return [field.slice(0, i), field.slice(i + 1)];
    }),
  );
  const { t, v1 } = fields;
  if (!/^\d+$/.test(t ?? "") || !v1) return false;

  if (Math.abs(receivedAtTs - Number(t)) > TOLERANCE_SEC) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(v1, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Test vector

Check your implementation against this before you go live. Note the compact JSON, with no spaces between tokens.


Secret	`axle_whsec_example`
Body	`{"id":"0198f0a1-2b3c-7d4e-8f90-1a2b3c4d5e6f","version":"v0.0.0","event_type":"user:onboarding:complete","created_at":"2026-08-11T14:02:11.482913Z","payload":{"site_id":"3c361164-5187-4b4b-8e8a-7b3f67c4d5a8","completed_at":"2026-08-11T14:02:11.301045Z","external_user_id":"1234567"}}`
`x-axle-sig`	`t=1786456932,v1=d4554b1fccf035c008a8040d20ad5a6c8e6f45299371945c7895084bf7300211`

Verifying that header against that body at a received_at within 300 seconds of 1786456932 should succeed. Changing a single byte of the body, the secret or the timestamp should make it fail.

If we’re part-way through rotating your secret you may hold two at once. Accept a request that verifies against either, and drop the old one when we confirm the rotation is done.

Responding

Return any 2xx once you’ve durably accepted the event. We time an attempt out after 10 seconds, so persisting the event and processing it afterwards is usually easier than doing the work inline.

Your response	What we do
`2xx`	Mark the delivery succeeded. Nothing more to do.
`4xx`	Treat it as a definitive refusal and stop. A malformed request or the wrong endpoint won’t improve with time.
`5xx`, timeout, connection error	Try again with backoff. See Retries.

A 4xx drops the event for good. If your handler can’t accept it right now, because a dependency is down for example, return a 5xx and we’ll come back to it.

Retries

We retry a failed delivery with exponential backoff: 30 seconds after the first failure, doubling each time, capped at 4 hours, with ±10% jitter. Retries stop 24 hours after the event’s created_at, not 24 hours after the first attempt, so a delivery that starts late has a shorter window. Once that budget is spent we stop, and we won’t replay the event later.

Delivery guarantees

Delivery is at-least-once and unordered, so make your handler idempotent.

Duplicates happen. A network failure after your endpoint has committed but before we see the response is indistinguishable from a failure, so we retry. Deduplicate on the envelope id, which is stable across every attempt of the same event, rather than on created_at or payload contents.
Order isn’t guaranteed. Retries interleave with fresh events, so a later event can arrive before an earlier one. Where order matters, sequence on created_at and treat an older event as a no-op if you’ve already applied a newer one.
Timing is best-effort. Events are normally delivered within seconds of created_at, but there’s no latency guarantee. Don’t gate a user-facing flow on a webhook arriving promptly.

Quick checklist

HTTPS endpoint live at the URL you gave us, one per environment.
x-axle-sig verified against the raw body before the event is acted on, and the test vector above passing.
Timestamps outside the 300-second tolerance rejected.
Events deduplicated on the envelope id.
Batched events handled per asset, with unrecognised asset_ids skipped rather than refusing the whole instruction.
2xx returned only once the event is durably accepted, 5xx on transient failure, and 4xx only for a genuine refusal.
Signing secrets stored as secrets, and kept distinct per environment.

If you hit anything that isn’t covered here, get in touch. We want to make sure this documentation is complete and correct, and that your integration works smoothly.

Next steps

Smart Charging integration

Where onboarding fits in the wider integration

Axle VPP integration

Where the vpp: events fit in a battery fleet integration

Home

Assets

Core workflows

EV Charging

Batteries & Heating

Registering your endpoint

Events

The envelope

Event payloads

`user:onboarding:complete`

`asset:dispatch:requested`

`vpp:asset:registered`

`vpp:dispatch:requested`

Verifying the signature

Test vector

Responding

Retries

Delivery guarantees

Quick checklist

Next steps

Smart Charging integration

Axle VPP integration

​Registering your endpoint

​Events

​The envelope

​Event payloads

​user:onboarding:complete

​asset:dispatch:requested

​vpp:asset:registered

​vpp:dispatch:requested

​Verifying the signature

​Test vector

​Responding

​Retries

​Delivery guarantees

​Quick checklist

​Next steps

Smart Charging integration

Axle VPP integration

Registering your endpoint

Events

The envelope

Event payloads

`user:onboarding:complete`

`asset:dispatch:requested`

`vpp:asset:registered`

`vpp:dispatch:requested`

Verifying the signature

Test vector

Responding

Retries

Delivery guarantees

Quick checklist

Next steps