Emit Heart Beat
POST /auth/v2/emitHeartbeat
The Heartbeat API must be integrated for Amazon to monitor the availability of your authentication device. The heartbeat must be invoked at least once per minute (recommended: once every 30 seconds).
The heartbeat:
- Keeps track of clock skews or desyncs between Amazon's devices and your authentication device.
- Keeps track of your device's availability for metrics, debugging, and alerting.
Important: If your heartbeat is missing for greater than 60 seconds, your device will be considered "unavailable." Once unavailability crosses a threshold, Amazon will alert your team through customer success channels.
Request Body Input
| Field | Required | Type | Description |
|---|---|---|---|
storeId |
Yes | String | External store identifier. |
deviceId |
Yes | String | Your 3P device identifier. |
isHealthy |
Yes | Boolean | true for normal operation. false when device is unhealthy or under maintenance. |
timestamp |
Yes | Long | Unix timestamp in ms from your device. |
Response Body Output, status 200
| Field | Type | Description |
|---|---|---|
heartbeatInterval |
Long | Current Amazon server time minus the timestamp of your previous heartbeat (ms). Use to detect clock drift. See Interpreting heartbeatInterval. |
emitHeartbeatMetadata |
Array | Reserved for future use. |
Interpreting heartbeatInterval
heartbeatInterval is calculated as:
heartbeatInterval = Amazon server time (now) - timestamp of your previous heartbeat
Because it compares Amazon's clock with your device's clock, it indicates whether your device clock is in sync. For example, if you call emitHeartbeat every 30 seconds:
| Your device clock | Expected heartbeatInterval |
|---|---|
| In sync with Amazon | Roughly 30 seconds |
| Behind Amazon | Higher than 30 seconds |
| Ahead of Amazon | Lower than 30 seconds |
Small deviations are expected because of the time it takes requests to reach the server, so do not use heartbeatInterval to adjust your device clock directly. Instead, treat a consistent deviation as a sign that your device clock has an issue (e.g., you may need to increase your NTP sync frequency).
