Webhook Notifications

Automated notifications of new content in Terminology Gateway

A webhook is an HTTP callback. When new content is published in the Terminology Gateway, a publishing event will be POSTed to each registered webhook, notifying their respective owners about the publication.

Webhook registration

Individual users can register for webhook notifications by contacting us and specifying the webhook endpoint. Upon registration, a unique api_id will be assigned to the webhook. Each notification POSTed by the Terminology Gateway will contain the api_id, allowing the endpoint to verify that the notification was indeed issued by the Terminology Gateway. The api_id must be echoed back by the webhook endpoint in the body of the notification response.

Webhook interface

The webhook endpoint must serve HTTP requests conforming to the following interface:

HTTP Request

{
  "api_id": "cb570e5a2748f349f9119431db836b3a23fdb6571afee34c0432d87220f2431b",
  "base_url": "https://termapi.infoway-inforoute.ca/rest/v1/",
  "notification_time": "2017110711:07:00",
  "targets": [
    {
      "id": "2.16.840.1.113883.2.20.6.1",
      "name": "Canadian Clinical Drug Data Set (CCDD)",
      "type": "package",
      "version": "20171016",
      "effective_date": "20171016",
      "publication_time": "2017103015:20:23",
      "message": "Monthly CCDD update for October 2017"
    },
    {
      "id": "2.16.840.1.113883.2.20.3.443",
      "name": "PrescribeIT",
      "type": "package",
      "version": "LPR2",
      "effective_date": "20171103",
      "publication_time": "2017110309:37:22",
      "message": "PrescriptionMedicinalCode version reflecting the October 2017 CCDD update"
    }
  ]
}
				

• api_id: as previously mentioned, each notification POST contains the api_id granted at registration.
• base_url: the base URL for the native REST API endpoint of the originating system. This can be used to call back the Terminology Gateway via APIs in order to programmatically download updated content.
• notification_time: the timestamp of the webhook notification in yyyyMMddHH:mm:ss format.
• targets: list of updated targets. Each entry in this array corresponds to a Terminology Gateway artifact (subset, codesystem, map, package) that was updated and is therefore subject to the notification. The target list will only include artifacts for which the user has registered to receive notifications. Users can register to receive notifications about content updates using the Terminology Gateway User Interface or by invoking the native REST APIs.
  
  Each of the notification targets contains the following fields:
  • id: the artifact id, typically an OID
  • name: the artifact name
  • type: the artifact type: subset, codesystem, package or map
  • version: the published version id
  • effective_date: the effective date associated to the artifact version, in yyyyMMdd format
  • publication_time: the publication time in yyyyMMddHH:mm:ss format
  • message: optional message describing the published artifact version

HTTP Request

HTTP Response code: 200 for success, any other response code will be interpreted as an error
Sample HTTP Response Body:

{
  "api_id": "cb570e5a2748f349f9119431db836b3a23fdb6571afee34c0432d87220f2431b",
  "result": "success",
  "message": "Successful processing of the webhook notification"
}

• api_id: as previously mentioned, each notification response must echo back the api_id granted at registration.
• result: success if the web hook notification was successful, any other value will be interpreted as an error.
• message: optional response message.

Error handling

When receiving an error as a result of a webhook notification, the Terminology Gateway will retry the notification four times at 15 minutes intervals. If still unsuccessful after four notification attempts, the system will drop the notification and will notify the user by email that the webhook couldn't be invoked.

Sample code

Demo code for a sample webhook endpoint can be found here: 

https://github.com/CanadaHealthInfoway/tgateway-webhook