Webhooks

Webhooks allow a client to configure user-defined HTTP callbacks that are triggered by different events that happen within the Healthx web application.  This allows a system to be notified in real-time of changes that happen in the Healthx web application, and in some cases respond and modify the change before it is committed.  Webhooks are divided into two types, pre-event (also called synchronous) and post-event (also called asynchronous).  Pre-event webhooks are triggered during a user interaction and allow a submitted change to be validated and/or modified before being saved.  Post-event webhooks are triggered after a change and are intended to inform subscribers of a change that has already occurred.

See the administrator documentation for info on configuring a webhook.

Security

All webhook receiver endpoints must meet the following requirements to help ensure the secure transmission of potentially sensitive data:

  • Endpoint must have a valid TLS certificate
  • URL must begin with https
  • URL must use a hostname, not an IP address
  • URL must not use localhost as the hostname
  • URL must not resolve to the Healthx application server
  • URL must use one of the following ports: { 80, 88, 443, 8443 }

All webhook request bodies are encrypted using a configurable algorithm.  Currently, only AES256 (CBC) is implemented.  The encryption key is generated when the webhook is configured, and is displayed as a 256-bit hex string.  The following is an example of decrypting a webhook request body implemented in C#:

string Decrypt(byte[] key, byte[] input) 
{
    using (var provider = new AesCryptoServiceProvider())
    {
        provider.Key = key;
        using (var ms = new MemoryStream(input))
        {
            // Read the first 16 bytes which is the IV.
            byte[] iv = new byte[16];
            ms.Read(iv, 0, 16);
            provider.IV = iv;

            using (var decryptor = provider.CreateDecryptor())
            {
                using (var cs = new CryptoStream(ms, decryptor, CryptoStreamMode.Read))
                {
                    using (var sr = new StreamReader(cs))
                    {
                        return sr.ReadToEnd();
                    }
                }
            }
        }
    }
}

All webhook requests are signed using the HMAC-SHA256 algorithm.  The encrypted body of the request is used as the input, and the signature is stored in the "X-Healthx-Signature-Hmac-Sha-256" request header.  The signature key is generated when the webhook is configured, and is displayed as a 256-bit hex string.  The signature should be checked by the receiver for every message to ensure that it is authentic and unaltered.  The following is an example of checking the signature implemented in C#:

bool ValidateSignature(byte[] bodyBytes, string signature, byte[] key)
{
    var hmac = new HMACSHA256(key);
    var sigBytes = hmac.ComputeHash(bodyBytes);
    return Convert.ToBase64String(sigBytes) == signature;
}

Events

The following are the message payloads that are sent for each event type.

Express Request Post-Event

{
  "ProcessId": "",
  "ProcessName": "",
  "Status": "",
  "FromUserId": "",
  "FromUserName": "",
  "Fields": []
}
Comments