> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amps.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Every webhook event and its payload.

Each event is delivered as a flat JSON body. See [Webhooks](/guides/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. |

<Callout icon="clock" color="#ED6D2C">
  **Coming soon.** Events for recurring schedules.
</Callout>

## Identify the event

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

```ts theme={null}
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 manufacturer accepted the command.

```json theme={null}
{
  "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 command didn't succeed. Branch on `errorCode`.

```json theme={null}
{
  "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](/guides/error-handling/error-codes). |
| `errorMessage` | Human-readable. Don't parse it. |
| `failedAt` | When the action failed. Replaces `completedAt`. |

## device.connected

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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](/guides/link-ui) so the end user can reconnect. It's usually present but can be missing, so handle both cases.

## Next steps

<CardGroup cols={2}>
  <Card title="Verify signatures" icon="shield" href="/guides/webhooks/verify-signatures">
    Confirm each request came from Amps.
  </Card>

  <Card title="Error codes" icon="list" href="/guides/error-handling/error-codes">
    Every `errorCode` a `push.failed` can carry.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.