Webhooks
A webhook (also called a web callback or HTTP push API) is a way for Spike to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately—unlike a typical API where you would need to poll for data very frequently to get it in real-time. This makes webhooks much more efficient for the provider and consumer. Webhooks are almost always faster than polling and require less work to implement. New data will be normalized and sent to your webhook URL address.
The endpoint you create must be configured to accept POST requests. It has to be an HTTPS-secured endpoint on your server with a distinct URL. You can enable/disable webhook messages and configure your webhook URL address in your app settings page in the developer console.
All Spike webhook events have the following structure in JSON format. In the example below you will find the base (root-level) JSON object for a webhook payload. "data": [...] field depends on provider and metrics available, therefore structure is dynamic. You can find examples of all possible fields and choosing specific metric. Also a summary of that is captured in this table.
Field | Description |
|---|---|
event_id | Unique identification assigned by Spike to each webhook notification. This is a synthetic ID, and it has no relation to the content of the notification. |
event_type | Webhook event type. |
timestamp | The time when the ping data from the provider was received. |
user_id | Spike user ID (UUID) |
client_user_id | User ID from your systems |
source | Data source (Garmin, Fitbit...) |
data_type | Data type (sleep, steps...) |
data | Data payload. The data format depends on the data type. All data types and examples can be found in the Metrics section. |
Requests will be retried 5 times with 180s intervals if your server returns a non-2xx response code, or if the request times out.
Some providers have limited availability of historic data of their users, but might not expose it over pull APIs. In such cases backfill functionallity has to be used. It is enabled on your dev-console
All Requests have the header X-Spike-Signature for request verification. A signature is HMAC (sha256) encoded string containing hexadecimal digits. The message value is event_id, the secret is your app secret token.