Understanding the Inform Push Service

Please note: The Inform Push Service requires additional licensing considerations. Please contact your account manager for more details

The Inform Push Service is an add-on component to our standard Inform Streaming and REST APIs and offers a third way to consume user-health data.

This service is used to provide notification of new or updated payloads following a push notification pattern to a customer provided endpoint.

The Inform Push Service also supports an FHIR transformation of user-health data.

Specifications

Customer Endpoints
An endpoint to the Pushed Data Receiver will need to be provided for Vaidic to send push notifications to. There are no specific requirements for the customer endpoint.

It is recommended that multiple instances of a Pushed Data Receiver are behind a load balancer for redundancy and scaling purposes. The Pushed Data Receiver will receive a payload of user-generated data from Validic, and it will ideally perform a light transformation of pertinent data and persist the data to a durable store for further processing. The custom processing should be responsible for transforming identifiers in the received JSON event in order to attribute the data to the appropriate user.

A durable storage system is a storage system resilient to data loss when encountered with service interruptions. Durable storage systems that provide ordering capabilities will help ensure the data is processed in the same order that it was received from Validic assuming the data is stored in the system based upon an appropriate keying strategy. As mentioned above, Validic recommends leveraging a keying strategy that incorporates unique user identifiers in the received event. The unique user identifiers should be used to build a key that will guarantee uniqueness across the user population.

Another advantage of durable storage systems is alleviating pressure on downstream components in the customer platform. If the rate of incoming data is greater than downstream platform components can handle, a durable storage system can respond to this backpressure by persisting events until consuming applications can process the events. This type of design helps create a more resilient architecture that is capable of handling spikes in incoming data. Some durable storage systems will allow the ability for consumers to re-process previously consumed events, which offers an additional strategy to reprocess data due to the need to augment previously processed data with additional metadata or to reprocess the data due to a bug that has been resolved.

It is important to understand the behavior and configuration requirements of the selected durable storage system to ensure it meets your specific objectives and requirements. Redundancy via multiple instances, disk sizing, and instance sizing (memory, CPU, network I/O) are all important considerations to review.

Authentication
Validic supports OAuth2 client credentials as the authentication protocol. To authenticate the push service customers need to provide the following to Validic:

Parameter	Description
token url	The endpoint used to make a request to the server for an access token
client id	The public identifier for the server
client secret	The private identifier is known only to the authorization server
grant type	Used to indicate the type of authentication credentials being requested
access token header	Any header that needs to be provided as part of the access token request

Retry Handling
The customer's server should reply with an HTTP 2xx status code to indicate successful processing of the received payload. An optional response body may also be provided as part of the response from the server.

By default, a server responding with an HTTP 401, 403, or 5xx status code will trigger an exponential backoff where retries will occur for up to 6 hours. If unsuccessful after 6 hours of retries the batch will be marked as failed and not retried again. Other error codes will not be retried.

Alternatively, a customer may define up to 3 custom ranges of HTTP codes to use for retry if the default retry logic does not meet their needs.

Push Triggers
Validic push notifications will be sent to customers when either of the threshold settings below is reached. Note: settings are configurable at the organization level.

Batch size - number of records per batch
Frequency - duration between batches

Payload Format

{
    "id": "d1ffd05a-4a03-421c-8a35-1fa898e9cc24",
    "data": [
        // Array of Validic resources
    ],
    "meta": {
        "count": 1
    }
}

The id provided in the payload is linked to a PushTransmitEvent that contains details about the batch transmission. These will include the Validic record IDs in the batch, the Validic user ID and customer uid associated with the records, the transmit event’s final status (success or failure), and any response information (HTTP status code and response body).

Example Payload

{
   "id":"d1ffd05a-4a03-421c-8a35-1fa898e9cc24",
   "data":[
      {
         "category":"other",
         "checksum":"18d34a6d347bfb5b23c9baace1f0fa7e",
         "created_at":"2019-07-16T17:27:09.936Z",
         "deleted_at":null,
         "end_time":"2019-07-09T06:59:59Z",
         "id":"860926cc4e432db37bdf62200363014e",
         "log_id":"2019-07-08",
         "metrics":[
            {
               "type":"energy_consumed",
               "origin":"unknown",
               "unit":"kcal",
               "value":0.0
            },
            {
               "type":"dietary_fiber",
               "origin":"unknown",
               "unit":"g",
               "value":0.0
            },
            {
               "type":"water",
               "origin":"unknown",
               "unit":"mL",
               "value":0.0
            },
            {
               "type":"carbohydrate",
               "origin":"unknown",
               "unit":"g",
               "value":0.0
            },
            {
               "type":"fat",
               "origin":"unknown",
               "unit":"g",
               "value":0.0
            },
            {
               "type":"protein",
               "origin":"unknown",
               "unit":"g",
               "value":0.0
            },
            {
               "type":"sodium",
               "origin":"unknown",
               "unit":"mg",
               "value":0.0
            }
         ],
         "name":"Unknown",
         "offset_origin":"profile",
         "segments":[

         ],
         "source":{
            "type":"fitbit",
            "device":null
         },
         "start_time":"2019-07-08T07:00:00Z",
         "tags":[

         ],
         "type":"nutrition",
         "user":{
            "organization_id":"5c45d9bc21419700018774a5",
            "user_id":"5d1cebd52141970001a8eca4",
            "uid":"marketplace-test"
         },
         "user_notes":[

         ],
         "utc_offset":-25200,
         "version":"1.0"
      }
   ],
   "meta":{
      "count":1
   }