Skip to main content

API notifications

You can manage state synchronization by using API queries to the LetsGetChecked resources.

A webhook notification is a type of API that is driven by events rather than requests. An API makes a request to another endpoint to receive a response, but a webhook allows one program to send data to another as soon as a particular event occurs. They deliver real-time updates to your application as soon as the updates are available, and are less resource intensive than APIs.

Configuring webhook notifications through the Order and Result APIs

Webhook notifications are triggered in real-time for any status update through the Order API and the Result API. The Order API and the Result API can be configured in one of the following ways:

  • One endpoint for orders and another endpoint for results.
  • One endpoint for both orders and results.

You receive a webhook notification when an order transitions to the ResultsAvailable status on the Order API and when the order transitions to the ResultsAvailable status on the Result API. Tip: The payload of webhook messages includes a Type property, which identifies when a notification is raised by the following changes:

  • Order API: An orders change
  • Result API: A results change

Webhook endpoints have an associated URL which can receive event details from your organization’s application. Webhooks use the event details to take any required actions, for example, fulfilling an order or returning results. For more information, see Payload structure.

LetsGetChecked uses webhook endpoints to identify changes to client resources. By using webhooks, when a change occurs to a client resource, the LetsGetChecked server submits a POST request to the endpoint URL that the client provides. LetsGetChecked acknowledges notifications that return a response with an HTTP 200 status code. For more information, see Error codes.

Payload structure

The submitted payloads have the following structure:

  • Resource identifiers, for example, the client order ID.

  • A URL to the LetsGetChecked server to query for changes.

  • A type that determines the type of resource, for example, Order or Result.

    Example: Order change notification

{
"body":{
"clientOrderId":"123456789",
"callbackURL":"{LGC-API}/1001/api/v1/orders/123456789/status",
"timestamp":"2022-03-04T11:35:17.43+00:00"
},
"type":"order"
}

Example: Results change notification

{
"body":{
"barcode":"LGC-XXX-XXX-XXX",
"alphaCode":"QWERTY",
"callbackURL":"{LGC-API}/1001/api/v1/results/{Barcode}?alphaCode={AlphaCode}&fields=status",
"timestamp":"2022-03-04T11:35:17.43+00:00"
},
"type":"Result"
}

Retry mechanism

LetsGetChecked attempts to deliver notifications up to 3 times. When a notification fails, the webhook mechanism retries 3 times every 2 hours. When the number of retries is exhausted, the webhooks mechanism fails. You can manually retry the webhook mechanism after a failed attempt.

Authentication for submitted payloads

There is no required authentication mechanism for payloads that are submitted because of the lightweight content of the payload.

You must inspect the domain of callback URLs that are received as part of the notifications at the client endpoint to ensure that no access tokens are leaked when accessing links.

If you require authentication, request that the notifications are signed by securely providing LetsGetChecked with a strong secret key (signing key) in base64 format.

When notifications are signed, the POST requests include the following details:

  • An authorization header with a type (scheme) value of LGC2-HMAC-SHA256
  • A credentials value of HMAC_SHA256 (signing key, request body). HMAC_SHA256 should be readily available in most modern stacks.
    Tip: LetsGetChecked uses the client’s secure HMAC (Hash-based message authentication code) key for authentication to ensure malicious attackers cannot directly access the service to obtain PHI. It is a more secure method of managing webhooks. For more information about the HMAC_SHA256 definition, see HMAC: Keyed-Hashing for Message Authentication.

The following example request displays the format of the authorization header and credentials value:

Authorization: LGC2-HMAC-SHA256 R2552Bi7MJz6iVmpCS7VtdT0UPbXq6NNC5+gmcRupps=

Request body
{
"lgcOrderRef":"d5364386-957f-41e1-8e75-282f7588133d",
"callbackURL":"{LGC-API}/123/order/123123123"
}
Signing key

KTNNPy4qyZuayiJuGUGetQGya46nTTb6ZRSmPNhU3y9R3u2cZY4whGsDOaKtgJmmQ5/aIzAVJNxorX2EjFD6kg==