Status Updates

Status Message: PUSH Approach

Overview

With the PUSH approach, HireRight sends statuses directly to the client once a status update occurs. This approach allows the client to receive real-time updates, however, this requires the client endpoint to be online at all times.

This is the HireRight recommended approach for order status messages.

The status message is PUSHed by HireRight to an HTTPS end-point provided during the Create Order (or Create I-9 Worksheet) operation in the statusUpdateUrls property.

"statusUpdatesUrls": [
    {
        "https://the_desired_webhook_address.com"
    }
],

Authentication

Status pushes support both Basic and OAuth2 Authentication. 

Basic Authentication

In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials>, where credentials is the base64 encoding of username and password joined by a single colon : .

Basic authentication refers to a header value of:
Authorization: Basic <base64 encoded username:password> 

Or another way to look at the format is as follows:
Authorization: Basic + base64(username+’:’+password)

For example, for credentials username/password it will look like this:
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

If Basic authentication is configured for the status pushes, outgoing status pushes will have this header present.

OAuth2 Authentication

In the OAuth2 Authentication, the following high level process flow is performed:

1. HireRight performs an API call to the provided OAuth2 endpoint to retrieve an OAuth token

2. OAuth token and when it will expire is returned in the response

3. HireRight sends the status push with the OAuth token

4. Token is validated, and if it is valid and not expired, OAuth authentication passes and status pushes are accepted

To utilize the OAuth2 Authentication method the following information must be provided to HireRight:

• OAuth2 Token Endpoint - 2 Options

  1. Option 1: Your OAuth2 Token Endpoint is configured as a static endpoint by HireRight within your integration configuration

  2. Option 2: A dynamic endpoint is included as part of the Create Order API operation within the StatusUpdatesAuthenticationURL flex field

• client_id and client_secret values

• Pre-defined scope can also be included (optional)

• Pre-defined resource can also be included (optional)

Format (Token Request):

GET<endpoint>?grant_type=client_credentials&client_id=<id>&client_secret=<secret>&scope=<scope if any>&resource=<resource if any>

Format (Success Response):

{
  "access_token": "<token>",
  "expires_in": "<in how many seconds the token is expired, from the time it was requested>",
  "token_type": "bearer"
}

Format (Failure Response):

{
  "status_code": <error code>,
  "errror": "<error>",
  "error_description": "<error description>"
}

HireRight uses the OAuth token for the status push:

Authorization: Bearer <access token>

Order Identification

The Order ID is included in the status message and accordingly, the client can identify the order (Same as Form ID for I-9s).

In addition, if another identifier is required, it is possible to send this identifier as a FlexField in the Create Order (or Create I-9 Worksheet) operation and the FlexField can be configured to be included in the status message.

Acknowledgements

HireRight expects a negative or positive acknowledgment in response to the status push.  Simply responding with a successful status code (200 level) will let the service know that the status push was received correctly, any other value will be tracked as a failure and will attempt a redelivery if configured.

Redelivery

Optionally, redelivery of the PUSHed status update can be enabled. Redelivery occurs on negative response status or low-level errors (bad HTTP connection, etc.).