Versions Compared

Version Old Version 14 New Version Current
Changes made by

Christian Borch

Jesper Nielsen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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:

...

Info

If you need to expose a 127.0.0.1 or localhost URI so it is publicly accessible for development and test, tools like https://ngrok.com can be used. (Himsa HIMSA does not endorse the tool, this is just a development tip).

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.

  • webhookVersion The version of the webhook implementation. V1 is version 1 (default) which only send one event per webhook request. V2 is version 2 which can send multiple events per webhook request.

  • maxEventsPerWebhookRequest is only applicable when webhookVersion is V2 and specifies the maximum number of events to send per webhook request. The valid range is from 1 to 10.

Example request:

Code Block
{
  "name": "Subscription name",
  "eventNotificationEndpointUrl": "https://myservice.com/noahevents",
  "eventNotificationSecret": "mysharedsecret",
  "eventSubscriptions": [
     {
      "type": "ActionCreated",
      "eventApi": true,
      "rtmApi": false,
      "filter": null
    },
    {
      "type": "ActionUpdated",
      "eventApi": true,
      "rtmApi": false,
      "filter": "DataTypeCode eq any (1,15,16)"
    }
  ],
  "webhookVersion": "V1",
  "maxEventsPerWebhookRequest": 5
}

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 The webhookVersion determines the message that your webhook endpoint will receive a :

  • V1 will send one request for each event matching your subscriptions. One request, one event.

  • V2 can send multiple events per webhook request.

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. If webhookVersion is V2 the message body will be an array of events. If webhookVersion is V1 the message body will be one event:

Code Block
            
{

  "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": null
      },
      {
        "Rel"GET: Patient""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-Signature: An HMAC-SHA256 signature of the request body that is base64 encoded, using the shared secret specified when setting up the event subscription.
    This lets your application verify that the notification really came from Noah. We highly recommend that you check the validity of the signature before processing the notification.

  • 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.

  • X-Webhook-Version: The version of webhook implementation (integer value either “1” or “2”). Use this to determine the content of the message body.

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.