Events

Each event is delivered as a flat JSON body. See Webhooks for setup, retries, and duplicates.

Event list

Event	Fires when
`push.completed`	An action reaches `completed`.
`push.failed`	An action reaches `failed`.
`device.connected`	An end user links a new device through Link UI.
`device.reconnected`	An end user links a device that was already connected.
`device.disconnected`	The device’s manufacturer credentials stop working.

Coming soon. Events for recurring schedules.

Identify the event

The body has no event type field. Branch on the fields present.

function eventType(event: Record<string, unknown>): string {
  if ("actionId" in event) return "errorCode" in event ? "push.failed" : "push.completed";
  if ("reconnectionUrl" in event) return "device.disconnected";
  return "device.connected or device.reconnected";
}

device.connected and device.reconnected have the same fields. If you need to tell them apart, check whether you already know the deviceId.

push.completed

The action reached completed. See action states for what completion confirms and how to check the device effect.

{
  "actionId": "action_qjSucnQFAk",
  "deviceId": "device_abc123",
  "deviceType": "battery",
  "command": "charge",
  "parameters": { "target": { "value": 80, "unit": "percent" } },
  "result": { "success": true },
  "completedAt": "2026-05-07T10:30:05.000Z"
}

Field
`actionId`	The action. Same as `id` on `GET /actions/{id}`.
`deviceId`	The device.
`deviceType`	`battery`, `ev_charger`, or `hvac`.
`command`	The command you sent.
`parameters`	The parameters you sent, or `null`.
`result`	`success` is `true`. A short `message` may be present.
`completedAt`	When the action completed.

push.failed

The action reached failed. Branch on errorCode.

{
  "actionId": "action_qjSucnQFAk",
  "deviceId": "device_abc123",
  "deviceType": "battery",
  "command": "charge",
  "parameters": { "target": { "value": 80, "unit": "percent" } },
  "result": { "success": false, "error": { "code": "DEVICE_OFFLINE", "message": "The device is currently offline at the manufacturer." } },
  "errorCode": "DEVICE_OFFLINE",
  "errorMessage": "The device is currently offline at the manufacturer.",
  "failedAt": "2026-05-07T10:30:05.000Z"
}

Same fields as push.completed, except:

Field
`result`	The error, or `null`. Don’t rely on it. Use `errorCode`.
`errorCode`	Why it failed. See Error codes.
`errorMessage`	Human-readable. Don’t parse it.
`failedAt`	When the action failed. Replaces `completedAt`.

device.connected

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

Field
`deviceId`	The device.
`deviceType`	`battery`, `ev_charger`, `hvac`, `solar_inverter`, or `vehicle`.
`timestamp`	When the event happened.

device.reconnected

Same fields as device.connected.

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

device.disconnected

Sent when a read or command fails with INVALID_CREDENTIALS. A failed command also sends its own push.failed.

{
  "deviceId": "device_abc123",
  "deviceType": "battery",
  "timestamp": "2026-05-07T11:00:00.000Z",
  "reconnectionUrl": "https://auth.amps.ai/app_abc123?manifestId=battery_example&reconnect=true"
}

reconnectionUrl opens Link UI so the end user can reconnect. It’s usually present but can be missing, so handle both cases.

Next steps

Verify signatures

Confirm each request came from Amps.

Error codes

Every errorCode a push.failed can carry.

Get started

API Reference

Guides

Cookbooks

Event list

Identify the event

push.completed

push.failed

device.connected

device.reconnected

device.disconnected

Next steps

Verify signatures

Error codes

​Event list

​Identify the event

​push.completed

​push.failed

​device.connected

​device.reconnected

​device.disconnected

​Next steps

Verify signatures

Error codes

Event list

Identify the event

push.completed

push.failed

device.connected

device.reconnected

device.disconnected

Next steps