Onegevity Health Intelligence

# Overview

Here you will find all the technical resources you need to integrate your system with the Onegevity Health Intelligence Service. If you haven't already we strongly suggest you read through the Getting Started page first to get an idea of the requirements and consider which integration pattern you plan on pursuing. With that information in hand, the following resources will provide you with the information you need to complete your integration.

# API credentials

The Onegevity APIs are secured using OAuth2 and, as such, you will be issued a client id and a client secret that will be used to obtain access tokens which are used to authenticate all requests to the API. During your onboarding process Onegevity will issue you your client id and secret. In the event that your secret is lost or believed to be compromised you can request a new one.

Keep credentials secure

Anyone with access to your client id and secret can access all of your patient's personal data, so it is vitally important that you safeguard this data in a protected location. Client secrets should not be checked into version control or be made accessible in a customers browser window.

# Environments

Your initial integration work will happen in our sandboxed staging environment which can be used to fully test all aspects of your integration before going live and using the production environment. You will be issued separate API credentials for each environment.

Environment Name API endpoint root
Staging https://staging-api.onegevity.com
Production https://api.onegevity.com

# Using the Onegevity UI-Kit JavaScript library

If you are planning on providing a web interface to your customers we highly recommend making use of the Onegevity UI-Kit JavaScript library that provides out-of-the box API integration and a polished user experience for all of the tasks necessary to complete the entire process lifecycle in your customers browser.

Click here to learn more about the UI-Kit JavaScript Library.

# Working directly with the Onegevity API

The Onegevity API is built upon the OpenAPI Specification Version 3.0.1 (opens new window) which means that you can choose to write your own API client making REST calls to the API endpoints you need or you may use tooling to generate client SDK libraries for you to interact with the API.

Onegevity maintains the following pre-built Client SDK libraries which are available for use:

Language Link
Java Maven (opens new window)
JavaScript NPM (opens new window)

# Authentication

If you are writing your own API client you will need to understand and implement the OAuth2 authorization flow that is appropriate for your use case:

  • If you will be calling the API from a backend system, the Client Credentials flow is recommended.
  • If you will be calling the API from a browser window, the Authorization Code flow must be used.

In either case you will need to request the appropriate OAuth2 scopes needed to access the various endpoints you'll be using. Scopes are documented per endpoint in our API Reference.

# API reference

Detailed information about each endpoint and request and response data types can be found in our interactive API documentation.

# Webhooks

Onegevity provides real-time notifications of processing lifecycle events by utilizing webhook technology. You will implement an endpoint in your own website or web services that Onegevity will call to notify your system of events as they occur. You may choose to implement a single, global webhook endpoint which will receive all events or you may register multiple endpoints, choosing which notifications you wish to receive at each.

# Message signature verification

To help ensure that you can trust the veracity of the message payloads delivered in webhook requests Onegevity will cryptographically sign each message with a shared secret specific to your account and send the signature as a HTTP request header ('X-Onegevity-Signature') along with the webhook payload. Your receiving code can then verify the computed signature of the message using the shared secret. Messages whose signatures do not match should be treated as malicious and discarded. While you are not required to implement message signature verification, it is highly recommended.

# Implementing message signature verification

The signature for a message is a base64-encoded string created by computing an HMAC using SHA256 as the message digest algorithm, seeded with your shared secret key. An example Java implementation is provided below using classes from the Java standard runtime library. If the computed signature matches the value provided in the X-Onegevity-Signature request header then the message is successfully verified as authentic.

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256");
hmacSha256.init(secretKey);

byte[] finalBytes = hmacSha256.doFinal(message.getBytes("UTF-8"));
String signature = Base64.getEncoder().encodeToString(finalBytes);

# List of webhook topics and payloads

The following is a list of all the webhook messages that the Onegevity system supports. You may register endpoints to receive only messages from specific topics or you may register endpoints to receive messages from all topics.

# patient.created

Sent when a patient record is created in the system

Example payload

{
    "id": 1519348,
    "patientIdentifier": "PO37011"
}

# patient.updated

Sent when a patient record is updated (for example: name change, birthdate change)

Example payload

{
    "id": 1519348,
    "patientIdentifier": "PO37011"
}

# order.created

Sent when an order is submitted for a patient to receive services

Example payload

{
    "id": 1519348,
    "orderIdentifier": "O13988",
    "patientIdentifier": "PO37011"
}

# order.updated

Sent when an order for a patient has new information added to it.

Example payload

{
    "id": 1519348,
    "orderIdentifier": "O13988",
    "patientIdentifier": "PO37011"
}

# kit.activated

Sent when a patient has activated a sample collection kit.

Example payload

{
    "id": 1519348,
    "orderIdentifier": "O13988",
    "patientIdentifier": "PO37011",
    "activationCode": "TH-YYYY"
}

# results.released

Sent when the final results for a patient order are complete and available to view.

Example payload

{
    "id": 1519348,
    "orderIdentifier": "O13988",
    "patientIdentifier": "PO37011"
}

# fulfillment.requested

Sent when a request for fulfillment has been received.

Example payload

{
    "id": 1519348,
    "requestorId": "F87101"
}

# fulfillment.accepted

Sent when a request for fulfillment has been reviewed and accepted and will be fulfilled.

Example payload

{
    "id": 1519348,
    "requestorId": "F87101"
}

# fulfillment.rejected

Sent when a request for fulfillment has been determined to be unfulfillable.

Example payload

{
    "id": 1519348,
    "requestorId": "F87101"
}

# fulfillment.canceled

Sent when a request for fulfillment has been canceled for any reason.

Example payload

{
    "id": 1519348,
    "requestorId": "F87101"
}

# fulfillment.shipped

Sent when a request for fulfillment has been completed and the package has been shipped.

Example payload

{
    "id": 1519348,
    "requestorId": "F87101",
    "trackingNumber": "99999999999",
    "trackingUrl": "http://tracking-url.com?99999999999"
}