API Reference: Webhooks

Webhook functionality will be made available in the near future as an Alpha release. During this phase, features and behavior are subject to change without notice and should not be relied upon in production environments.

For access or support, contact your BloodCOMM Engineering Point of Contact. Prior to development, ensure that a Sandbox account has been configured; if one has not been established, setup will be required

BloodCOMM is able to send out webhooks based on specific events, mirroring the user-facing alert functionality.

Note: Webhook functionality mirrors the user-facing alert system. Consequently, Administrative and Blood Bank organizations will not receive webhooks for devices within organizations to which they have been granted remote access.

However, webhooks for blood-related alerts will still be sent on behalf of remote-access organizations.

HMAC Secrets

BloodCOMM requires an HMAC secret to be generated prior to sending webhooks. This allows the receiving software to verify the authenticity of the webhook.

HMAC-SHA256 signatures are sent within the X-BloodCOMM-Signature header on every outbound POST. Pseudocode is below for parsing the signature:

// On receipt of a webhook POST:
rawBody      = request.body.bytes; // raw bytes — do NOT parse JSON first

headerSig    = request.headers["X-BloodCOMM-Signature"]  // "sha256=<hex>"
expectedSig  = "sha256=" + HMAC_SHA256(key=YOUR_SECRET, message=rawBody).toHex()

if not TIMING_SAFE_EQUAL(headerSig, expectedSig):
    return 401 Unauthorized

payload = JSON.parse(rawBody)              // safe to parse now

Webhook Payloads

All webhooks will POST via standard HTTPS REST commands. Your software should respond to the POST with a 200 response, such that the webhook can be marked as sent successfully. Other responses will trigger an automatic retry mechanism, with an exponential backoff. After 5 tries, the webhook will be marked as "failed".

Webhooks all contain the following standard set of key/value pairs within the BODY of the request:

BaseData = {
  /** Alert type discriminator (i.e. device-temperature). */
  alert: string;
  /** Unix seconds — when the alert was first detected. */
  time: number;
  /** Owning org UUID */
  organization: string;
  /** Present (and true) only on test fires — never on real alerts. */
  test?: true;
}

The following webhooks are available:

Alert	Description
`device-temperature`	A device has crossed a defined temperature threshold (increasing or decreasing).
`device-battery`	A device has crossed a battery threshold, decreasing.
`device-duration`	A device has crossed a duration (holdover) threshold, decreasing.
`blood-transfusion`	A Blood Bag has been marked as Transfused.

Additional webhooks are in development, contact BloodCOMM Support for more information.

Device Webhooks

Device webhooks are prepended with device- as alert type. They extend the base webhook data with the following standard set of device-centric data:

DeviceBaseData = {
  /** Device type (model, i.e. APRU-006L) */
  deviceType: string;
  /** Device serial number (i.e. 0001234) */
  serialNumber: string;
  /** Optional human-friendly device nickname. */
  nickname?: string;
  /** Current temperature (°C). */
  temperature: number;
  /** Current battery level (%). */
  battery: number;
  /** Current holdover level (hrs). */
  duration: number;
  /** Unix seconds — timestamp of the sensor reading that triggered the alert. */
  timestamp: number;
  /** Threshold value that was crossed (i.e. temperature °C, battery, etc) % */ 
  thresholdCrossed: number;
}

Each webhook includes additional data, depending on the event type:

`device-temperature`

{
  ...BaseData,
  ...DeviceBaseData,
  /** Temperature reading immediately before the threshold crossing. */
  previousTemperature: number;
}

`device-battery`

{
  ...BaseData,
  ...DeviceBaseData,
  /** Battery level immediately before the threshold crossing. */
  previousBattery: number;
}

`device-duration`

{
  ...BaseData,
  ...DeviceBaseData,
  /** Holdover level immediately before the threshold crossing (hrs). */
  previousDuration: number;
  /** Unix seconds — predicted time of temperature
       excursion based on remaining Duration. */
  predictedExcursion: number;
}

Blood Webhooks

Blood webhooks are prepended with blood- as alert type. They extend the base webhook data with the following standard set of blood-centric data:

BloodBaseData = {
  /** Unmodified ISBT-128 DIN barcode value. (appppyynnnnnnff) */
  din: string;
  /** Expiration date in ISBT-128 format (cyyydddhhmm). */
  expirationDate: string;
  /** ISBT-128 product code (e.g., E00V0000). */
  productCode: string;
  /** ISBT-128 blood type code (e.g., 5100 => O+). */
  bloodType: string;
}

Each webhook includes additional data, depending on the event type:

`blood-transfusion`

{
  ...BaseData,
  ...BloodBaseData,
  /** Unix seconds — when the transfusion event was recorded. */
  transfusionTime: number;
  /** Non-PHI receiving facility name (optional). */
  receivingFacilityName?: string;
  /** Non-PHI facility identifier(optional). */
  receivingFacilityID?: string;
  /** Non-PHI first responder or clinician identifier(optional). */
  firstResponderID?: string;
  /** Non-PHI transport agency identifier. */
  transportAgencyID?: string;

  /** Optional note field for additional context. */
  note?: string;
}