Page Comparison

See main page about choosing event integration and to learn about general concepts: Event Integrations

Set up of webhook

1: Create a webhook endpoint

To receive events your app must provide an endpoint that meet following requirements:

...

2: Create an event subscription

To set up a new webhook the app itself will need to call the Noah ES API to create an event subscription. To create a webhook event subscription you need to specify the following in the request:

• eventNotificationEndpointUrl Add the full URI for your webhook (e.g. https://www.example.com/noahevents)

• eventNotificationSecret A shared secret used to compute a HMAC-SHA256 signature of the request body. The secret is created by the HIMSA Member Company developer.

  • The secret can’t be retrieved from the Noah ES API, so it’s up to the app to manage and store the secret so it can be used to verify the authenticity and integrity of the data.

• eventSubscriptions For each event type specify if it should be sent via webhook by setting eventApi to true for the event type.

...

Once you make a HTTP POST/PUT request for an event subscription, an initial "verification request" will be made to the specified eventNotificationEndpointUrl that the endpoint must successfully respond to.

Receiving Events

Your webhook endpoint will receive a request for each event matching your subscriptions. One request, one event.

Message Body

When an event in your subscription occurs, we'll send an HTTP POST request to your web hook URL. The event will be in the Content-Type: application/json format:

            
{

  "TenantId": "730388bc5b04ef2e-af115885-468d4d95-bd2ea1e3-cec0f273a822852a2ba9cef1",

  "NotificationEventSubscriptionIdNotificationEventId": "19efd771be72d402-f3f7d99e-428749f2-a4daa49c-f9f16adc0552c468025bb69f",
   "NotificationEventIdCorrelationId": "6e665039762fe18a-b4ec488f-41b84c43-96ac9813-614b53eeea100c549aace3f6",

  "CorrelationIdNotificationEventSubscriptionId": "66861d3fe6b6ecfd-37b9e170-441b4bec-9f008657-f60181fa49d22d9f20661af7",
   "EventTypeTransmissionDate": "PatientCreated2024-02-15T08:33:45.5642258Z", 

  "TransmissionDateEventType": "2017-03-02T14:37:07.9395339ZPatientCreated",
   "Event": {
      "ResourceId": "b93009e0be92eeb4-07b95e3f-42604a79-bf2aa13d-a2c02cb230c83658db31e1f1",
 
    "EventDate": "20172024-0302-02T1415T08:3733:0745.9395339Z5599285Z",
      "UserAccountIdReferences": "1483eea6-ac34-4502-9e32-abc8bd831650",[
      "References":[{
        "Rel": "selfselfLegacyId",
        "HrefResourceId": "https://himsacloud.com/730388bc-af11-468d-bd2e-cec0f273a822/api/v1/patients/b93009e0-07b9-4260-bf2a-a2c02cb230c81",
        "TitleHref": "GET Patient"null
      },
      {
        "Rel": "self",
      }]  "ResourceId": "be92eeb4-5e3f-4a79-a13d-3658db31e1f1",
 } }      "Href": "https://localhost:52599/5b04ef2e-5885-4d95-a1e3-852a2ba9cef1/api/Patients/be92eeb4-5e3f-4a79-a13d-3658db31e1f1"
      }
    ]
  }
}  

Note that the payload of the notification request does not include the actual data e.g. the updated patient data, It only informs your application of which patient have changes. You will then want to call the referenced resource to get the actual updated data.

Message Headers

Every notification request will include the following headers:

...

• X-Hub-Origin: The origin header contains a the origin of the event message - it will be “https://api.*.noah-es.com“. It can be used by the receiver to check if the event is from an origin that is accepted or for internal routing in the receiver.

• X-Hub-TransmissionAttempt: The TransmissionAttempt header contains the number of times the sender has tied to send the specific notification, so if it is the first time the notification is transmitted the TransmissionAttempt header value will be “1”. If the two first requests failed the “TransmissionAttempt” value will be “3” for the third transmission.

• X-Message-ID: Unique ID for the webhook payload (same as NotificationEventId in the event message). Use this ID to avoid processing a web hook event multiple times.

Error handling

When Noah ES sends notification requests to your request URL, we ask that you return a HTTP 200 OK for each event you successfully receive.

Failure conditions

We consider any of these scenarios a single failure condition:

• we are unable to negotiate or validate your server's TLS certificate

• we wait longer than 5 seconds to receive a valid response from your server

• we encounter HTTP redirects to follow

• we receive any other response than a HTTP 200-series response

• we just couldn't seem to connect to your server. Maybe we couldn't find it in DNS or maybe your host is unreachable.

Retry policy

To deal with transient network errors every notification request will be retried 3 times with exponential backoff starting with a delay of 2 sec.

...

If the event subscription is updated then the retry wait time is short circuited and delivery of event message is retried immediately.

Retention period

Event messages will be kept for 7 days. If the event messages can't be delivered within that period then event messages will start to be lost.

Best practices

• Tolerate minor changes in event type structures. Expect additional fields you haven't encountered before and fields that are only conditionally present.

• De-couple your ingestion of events from processing and reacting to them. Especially when working with large workspaces, many workspaces, or subscribing to a large number of events. Quickly respond to events with HTTP 200 and add them to a queue before doing amazing things with them.