Skip to main content

​
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

Real-time Updates

Get instant notifications when events occur

Reduced API Calls

No need to poll for status updates

Efficient Processing

Process events asynchronously in your application

Better UX

Provide faster updates to your users

​
Setting Up Webhooks

1

Configure Endpoint

Add your webhook URL in the Amps AI Dashboard under Webhooks settings
2

Subscribe to Events

Select which webhook events you want to receive:
  • Action completion events (push.completed)
  • Action failure events (push.failed)
3

Verify Endpoint

Verify your endpoint can receive POST requests and return 200 status codes
4

Handle Payloads

Process incoming webhook payloads and verify signatures for security

​
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)

Webhook Types Reference

See detailed webhook payloads and examples

​
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.
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).

​
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: 
{
  "actionId": "act_abc123",
  "deviceId": "device_xyz789",
  "deviceType": "battery",
  "command": "auto.balanced",
  "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: 
{
  "deviceId": "device_abc123",
  "deviceType": "battery",
  "timestamp": "2026-06-01T10:30:00.000Z"
}
See webhook types for the full field reference, including the push.failed shape and the device.disconnected reconnectionUrl.

​
Security

Always verify webhook signatures to ensure requests are from Amps AI. Never process unsigned webhooks.
Webhooks include a signature header for verification: 
svix-signature: v1,abc123def456...

Webhook Security Guide

Learn how to verify webhook signatures

​
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 for temporary endpoints
  • Test locally with ngrok 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

Webhook Types

See all webhook event types and payloads

Security

Learn about webhook signature verification