Webhook

Format

Webhooks share the same general layout of data regardless of the event type.

The webhook is a standard HTTP POST request with an application/json encoded body. Depending on the event type the JSON object has different fields but the event and patient are always present.

Below is an example of the patient.config event.

{
    "event": "patient.config",
    "patient": {
        "refId": "609856950238678-bjqq3l8orflahtda",
        "name": "Zackary",
        "bsn": "919ii9d3n9",
        "umoId": "c12674c5-2c35-4ace-ac55-68603cd85803",
        "dateOfBirth": "2012-02-01T00:00:00.000Z",
        "tags": {
            "status": "active",
            "age": 34
        },
        "config": {
            "alertIfEmpty": true,
            "alertIfNote": true,
            "alertInactiveDays": 5,
            "triggers": {
                "8462-4": {
                    "code": "8462-4",
                    "display": "Diastolic blood pressure",
                    "valueKey": "value",
                    "notes": "value>100.0",
                    "logic": {
                        ">": [
                            {
                                "var": "valueQuantity.value"
                            },
                            100
                        ]
                    }
                },
                "8480-6": {
                    "code": "8480-6",
                    "display": "Systolic blood pressure",
                    "valueKey": "value",
                    "notes": "value>130",
                    "logic": {
                        ">": [
                            {
                                "var": "valueInteger"
                            },
                            130
                        ]
                    }
                }
            }
        },
        "manager": "000000000000000000000000",
        "tenant": "aaaaaaaaaaaaaaaaaaaaaaaa",
        "createdAt": "2023-02-06T18:11:03.967Z",
        "updatedAt": "2023-02-06T18:19:04.086Z",
        "id": "63e142b748defd5e9c88d124"
    }
}

Http Headers

Header	Description
x-actimi-subscriber	subscriber Id that was subscribed to this event
x-actimi-custom	custom data. It can be specified with custom field when subscriber is created or updated
x-actimi-signature	Security signature. It is base64 encoded HMAC SHA256 of the raw request body with the `secret` value of a subscriber. See create user for details

Signature validation

To ensure that the messages you are getting are coming from the trusted source it is highly recommended to check its signature supplied in x-actimi-signature header

To check a signature you have to calculate a new one using HMAC with SHA256 hash on a raw message body and a secret value shared with the subscriber.

See the example code for expressjs below

import express from "express"
import CryptoJs from "crypto-js"

const createSignature = (secret: string, body: string) => {
  const data = CryptoJs.HmacSHA256(body, secret)
  return data.toString(CryptoJs.enc.Base64)
}

const app = express()
//We use json middleware to access and check the signature of raw data
app.use(express.json({
  verify: (req, res, buf, encoding) => {
    const sig = createSignature(secret, buf.toString())
    if (sig != req.headers["x-actimi-signature"]) {
      throw new Error("Signature error")
    }

  }
}))

Return value

Webhook is a standard HTTP request. Upon success, it has to return HTTP 200 OK status. If there is no response or 4xx/5xx status code the webhook will be invoked (up to 5 times) with exponential backoff retry