Types

Webhook bodies are flat. The fields below are the body verbatim, delivered as the HTTP POST body. The event type and the per-delivery ID ride in the svix-id, svix-timestamp, and svix-signature headers, not in the body. There is no event or data envelope to unwrap: a field like command sits at the top level, so you read body.command, never body.data.command.

Device connection events

Connection events track a device’s link to your account. They carry the device identifiers plus a timestamp, and device.disconnected adds a reconnectionUrl when the OEM’s auth flow supports re-entry.

`device.connected`

Fires when a new device finishes registration through the Auth Journey.

{
  "deviceId": "device_abc123",
  "deviceType": "battery",
  "timestamp": "2026-06-01T10:30:00.000Z"
}

`device.reconnected`

Fires when an already-registered device’s credentials are refreshed.

{
  "deviceId": "device_abc123",
  "deviceType": "battery",
  "timestamp": "2026-06-01T12:00:00.000Z"
}

`device.disconnected`

Fires when stored credentials become invalid. The body carries a reconnectionUrl pointing at the Auth Journey in reconnection mode when the OEM’s auth flow supports re-entry.

{
  "deviceId": "device_abc123",
  "deviceType": "battery",
  "timestamp": "2026-06-01T11:00:00.000Z",
  "reconnectionUrl": "https://auth.amps.ai/?reconnect=true&token=..."
}

Action events

Webhooks are only sent for actions that reach a terminal state (completed or failed). When an action is first created, it starts in the acknowledged state, but no webhook is sent at that time. You can check the action status by polling the API at GET /actions/{actionId} (one device-agnostic route for every device type), but webhooks are only delivered when the action completes or fails.

`push.completed`

Fires when an action completes successfully. This webhook is only sent when the action reaches the completed terminal state. The body mirrors the dispatch and the read response: the canonical command, the constraints-only parameters, the clean deviceType, and a result.

{
  "actionId": "act_abc123",
  "deviceId": "device_xyz789",
  "deviceType": "hvac",
  "command": "auto.maintain",
  "parameters": {
    "heatSetpoint": { "value": 20, "unit": "celsius" },
    "coolSetpoint": { "value": 24, "unit": "celsius" }
  },
  "result": {
    "success": true,
    "message": "Command executed successfully"
  },
  "completedAt": "2026-06-01T10:30:05.000Z"
}

`push.failed`

Fires when an action fails to complete. This webhook is only sent when the action reaches the failed terminal state. The failure is reported through top-level errorCode and errorMessage; result is null on a failed action. The errorMessage is the API-owned message for the code; the manufacturer’s raw text never reaches the payload.

{
  "actionId": "act_abc123",
  "deviceId": "device_xyz789",
  "deviceType": "hvac",
  "command": "auto.maintain",
  "parameters": {
    "heatSetpoint": { "value": 20, "unit": "celsius" },
    "coolSetpoint": { "value": 24, "unit": "celsius" }
  },
  "result": null,
  "errorCode": "DEVICE_OFFLINE",
  "errorMessage": "The device is currently offline at the manufacturer.",
  "failedAt": "2026-06-01T10:30:05.000Z"
}

Action states

When you send a push command via the API, the action goes through the following states:

acknowledged - The action has been created and is being processed immediately. No webhook is sent at this stage.
scheduled - The action has a start time and will execute at that time. Scheduled actions (battery, EV charger, or HVAC) can be cancelled via POST /actions/{actionId}/cancel.
completed - The action completed successfully. A push.completed webhook is sent.
failed - The action failed to complete. A push.failed webhook is sent.
cancelled - The action was cancelled before execution. No webhook is sent.

To check the status of an action while it’s still processing, use the action polling endpoint, GET /actions/{actionId} (one device-agnostic route for every device type). Webhooks are only sent for terminal states (completed or failed).

Common error codes

Codes that commonly appear as errorCode on a push.failed event. Every code is drawn from the same canonical taxonomy the API uses on push responses, and the errorMessage is the API-owned message for the code. See the device error codes reference for the full set and the exact message per code.

string

The device is currently offline at the manufacturer.

string

The device manufacturer does not support this command.

string

The device manufacturer did not respond in time.

string

The device manufacturer is rate limiting requests. Please try again shortly.

string

The device manufacturer rejected the supplied credentials.

Webhook payload fields

The body is flat. These are the top-level fields a push event carries.

string

required

Identifier of the action that reached a terminal state. Dedupe push events by this value, or by the svix-id header.

string

required

Identifier of the device the action targeted.

string

required

The clean device type, for example battery, hvac, or ev_charger.

string

required

The canonical command that was dispatched, for example charge or auto.balance.

object

The constraints-only parameters for the command, or null.

object

The OEM result envelope on push.completed (result.success is true). It is null on push.failed — read errorCode and errorMessage for the failure.

string

ISO 8601 timestamp for the terminal transition on a push.completed event.

string

Machine-readable failure code, present on push.failed.

string

Human-readable failure description, present on push.failed.

string

ISO 8601 timestamp for the terminal transition on a push.failed event.

Handling webhooks

Idempotency

The per-delivery ID arrives in the svix-id header. Use it as the idempotency key to drop duplicates. Push events can also be deduped by actionId.

// Store processed delivery IDs from the svix-id header.
const processedDeliveries = new Set();

function handleWebhook(req) {
  const deliveryId = req.headers["svix-id"];
  if (processedDeliveries.has(deliveryId)) {
    return; // Already processed
  }

  // Process the flat body
  processEvent(req.body);

  // Mark as processed
  processedDeliveries.add(deliveryId);
}

Response requirements

Your webhook endpoint must:

Return 200 OK for successful processing
Respond within 30 seconds
Handle duplicate deliveries gracefully

Next steps

Webhook Overview

Learn about webhook setup

Security

Verify webhook signatures

Get Started

Concepts

API Reference

Guides

Quick reference

More

Device connection events

`device.connected`

`device.reconnected`

`device.disconnected`

Action events

`push.completed`

`push.failed`

Action states

Common error codes

Webhook payload fields

Handling webhooks

Idempotency

Response requirements

Next steps

Webhook Overview

Security

​Device connection events

​device.connected

​device.reconnected

​device.disconnected

​Action events

​push.completed

​push.failed

​Action states

​Common error codes

​Webhook payload fields

​Handling webhooks

​Idempotency

​Response requirements

​Next steps

Webhook Overview

Security

Device connection events

`device.connected`

`device.reconnected`

`device.disconnected`

Action events

`push.completed`

`push.failed`

Action states

Common error codes

Webhook payload fields

Handling webhooks

Idempotency

Response requirements

Next steps