Skip to main content

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.

​
What are Webhooks?

Webhooks deliver Amps platform events to your endpoint over HTTP POST as they happen, replacing the need to poll the API. Action lifecycle events (push.completed, push.failed) fire when an action reaches terminal state.

​
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 (device.connected, device.disconnected, device.reconnected) are planned but not yet implemented. These events will be available in a future release.

​
Webhook Delivery

​
Delivery Guarantees

  • At-least-once delivery: Webhooks may be delivered multiple times
  • Idempotency: Use the eventId 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 (e.g., GET /battery/actions/{actionId}) to check status while processing. Webhooks are only sent when actions reach terminal states (completed or failed).

​
Webhook Payload Structure

All webhooks follow a consistent structure: 
{
  "event": "push.completed",
  "eventId": "evt_abc123",
  "timestamp": "2025-01-23T10:30:00.000Z",
  "data": {
    "actionId": "act_abc123",
    "deviceId": "device_xyz789",
    "actionType": "set_permanent_hold",
    "completedAt": "2025-01-23T10:30:05.000Z"
  }
}

​
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,abc123...,def456...

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 eventId
  4. Log all events for debugging

​
Next Steps

Webhook Types

See all webhook event types and payloads

Security

Learn about webhook signature verification