> ## 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.

# How to receive webhooks

> Configure a webhook endpoint for push and device connection events. Flat payloads, at-least-once delivery, ~10s in live, ~3min in sandbox, HMAC-signed.

## What are Webhooks?

Webhooks deliver Amps platform events to your endpoint over HTTP POST as they happen, replacing the need to poll the API. Push events (`push.completed`, `push.failed`) fire when an action reaches a terminal state. Device connection events (`device.connected`, `device.reconnected`, `device.disconnected`) fire when a device's link to your account changes.

## Benefits

<CardGroup cols={2}>
  <Card title="Real-time Updates" icon="bolt">
    Get instant notifications when events occur
  </Card>

  <Card title="Reduced API Calls" icon="arrow-down">
    No need to poll for status updates
  </Card>

  <Card title="Efficient Processing" icon="cog">
    Process events asynchronously in your application
  </Card>

  <Card title="Better UX" icon="user">
    Provide faster updates to your users
  </Card>
</CardGroup>

## Setting Up Webhooks

<Steps>
  <Step title="Configure Endpoint">
    Add your webhook URL in the [Amps AI Dashboard](https://app.amps.ai) under Webhooks settings
  </Step>

  <Step title="Subscribe to Events">
    Select which webhook events you want to receive:

    * Action completion events (`push.completed`)
    * Action failure events (`push.failed`)
  </Step>

  <Step title="Verify Endpoint">
    Verify your endpoint can receive POST requests and return 200 status codes
  </Step>

  <Step title="Handle Payloads">
    Process incoming webhook payloads and verify signatures for security
  </Step>
</Steps>

## Webhook event types

### Action events

Webhooks are only sent for actions that reach a terminal state. When you send a push command:

1. The action is created in `acknowledged` state (immediate) or `scheduled` state (when `start` is provided). No webhook is sent.
2. You can poll the API to check status while it's processing. Scheduled actions can be cancelled.
3. When the action completes or fails, a webhook is sent.

**Available webhook events:**

* **`push.completed`**: An action completed successfully (terminal state)
* **`push.failed`**: An action failed to complete (terminal state)

<Card title="Webhook Types Reference" icon="list" href="/reference/webhook-types">
  See detailed webhook payloads and examples
</Card>

### Device events

Device connection webhooks fire when a device's link to your account changes:

* **`device.connected`**: a new device finishes registration through the Auth Journey
* **`device.reconnected`**: an already-registered device's credentials are refreshed
* **`device.disconnected`**: stored credentials become invalid

A `device.disconnected` body carries a `reconnectionUrl` pointing at the Auth Journey in reconnection mode when the OEM's auth flow supports re-entry.

## Webhook Delivery

### Delivery Guarantees

* **At-least-once delivery**: Webhooks may be delivered multiple times
* **Idempotency**: Use the `svix-id` header to handle duplicate deliveries
* **Retries**: Failed deliveries are automatically retried with exponential backoff
* **Timeout**: Your endpoint should respond within 30 seconds

### Delivery Timing

* **Action events**: Delivered after action reaches a terminal state (`completed` or `failed`). Typically 10 seconds for live environment, 3 minutes for sandbox environment after the action completes.

<Tip>
  Actions start in `acknowledged` state (immediate) or `scheduled` state (when `start` is provided). Use the action polling endpoint, `GET /actions/{actionId}` (one device-agnostic route for every device type), to check status while processing. Webhooks are only sent when actions reach terminal states (`completed` or `failed`).
</Tip>

## Webhook payload structure

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

A push event carries the action state:

```json theme={null}
{
  "actionId": "act_abc123",
  "deviceId": "device_xyz789",
  "deviceType": "battery",
  "command": "auto.balance",
  "parameters": null,
  "result": { "success": true, "message": "Mode applied" },
  "completedAt": "2026-06-01T10:30:05.000Z"
}
```

A device connection event carries the device identifiers and a `timestamp`:

```json theme={null}
{
  "deviceId": "device_abc123",
  "deviceType": "battery",
  "timestamp": "2026-06-01T10:30:00.000Z"
}
```

See [webhook types](/reference/webhook-types) for the full field reference, including the `push.failed` shape and the `device.disconnected` `reconnectionUrl`.

## Security

<Warning>
  Always verify webhook signatures to ensure requests are from Amps AI. Never process unsigned webhooks.
</Warning>

Webhooks include a signature header for verification:

```
svix-signature: v1,abc123def456...
```

<Card title="Webhook Security Guide" icon="shield" href="/guides/webhooks/verify-signatures">
  Learn how to verify webhook signatures
</Card>

## Testing Webhooks

### Sandbox Testing

Use the sandbox environment to test webhook delivery:

* Webhooks are delivered with a 3-minute delay after action completion (configurable)
* Test error scenarios safely
* Mock device actions can be tested

### Webhook Testing Tools

* Use tools like [webhook.site](https://webhook.site) for temporary endpoints
* Test locally with [ngrok](https://ngrok.com) or similar tunneling services
* Use the dashboard to view webhook delivery logs

## Error Handling

Your webhook endpoint should:

1. **Return 200 OK** for successful processing
2. **Return 4xx/5xx** to trigger retries
3. **Process idempotently** using the `svix-id` header
4. **Log all events** for debugging

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhook Types" icon="list" href="/reference/webhook-types">
    See all webhook event types and payloads
  </Card>

  <Card title="Security" icon="shield" href="/guides/webhooks/verify-signatures">
    Learn about webhook signature verification
  </Card>
</CardGroup>