Tutorial: Subscribe to Topic (R4B)


This tutorial requires configuring your Aidbox instance with a specific SubscriptionTopic for Observation resource. Additionally, a web service that will receive rest-hook notifications is required. This Repo contains a suitable template project, which should be used for this tutorial.

Choose a topic

Use FHIR API to discover available topics. Each topic contains URL field which should be specified as a criteria field of Subscription.

GET /fhir/SubscriptionTopic
accept: application/json

In response, one configured topic is available, with "url": "http://aidbox.app/SubscriptionTopic/observations".

Create Subscription (R4B)

Create a Subscription resource with all the necessary attributes.

Profile http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription is required for R4B.

Most interesting part are:

  • "criteria" : "http://aidbox.app/SubscriptionTopic/observations" - the Topic that a subscription are created for.

  • {"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count", "valuePositiveInt" : 2} notification will be delivered immediately when specified number of suitable events is met.

  • {"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period", valueUnsignedInt" : 20} period in seconds when all available to the moment messages will be delivered. if no messages collected - heartbeat event will be fired.

  • {"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content", "valueCode" : "id-only"} notification will only contain ids of resources. The other options are full-resource and empty.

  • "endpoint" : "http://subscription-demo-server:9000/callback-test-1" endpoint to which POST request with notifications will be sent.

  • {"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria", "valueString" : "Observation?value=42"} specifies, that only observation with value=42 should be delivered for this notification. Available filters or resources may be configured in SubscriptionTopic.

POST /fhir/Subscription
content-type: application/json
accept: application/json

  "meta" : {
    "profile" : [ "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription" ]
  "criteria" : "http://aidbox.app/SubscriptionTopic/observations",
  "channel" : {
    "extension" : [ {
      "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
      "valueUnsignedInt" : 20
    }, {
      "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
      "valueUnsignedInt" : 60
    }, {
      "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
      "valuePositiveInt" : 2
    } ],
    "type" : "rest-hook",
    "endpoint" : "http://subscription-demo-server:9000/callback-test-1",
    "payload" : "application/fhir+json",
    "_payload" : {
      "extension" : [ {
        "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
        "valueCode" : "id-only"
      } ]
  "_criteria" : {
    "extension" : [ {
      "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
      "valueString" : "Observation?value=42"
    } ]
  "resourceType" : "Subscription",
  "reason" : "R4/B Test Topic-Based Subscription for Observation",
  "status" : "requested",
  "id" : "test-sub-1",
  "end" : "2024-12-31T12:00:00.000-00:00"

As a result of this step Aidbox will try to perform a handshake with the subscriber service. By default Aidbox expects Status:200 response.

You may notice handshake event in demo server UI:

After the successful handshake, the status of the Subscription will be active.

GET /fhir/Subscription/test-sub-id/$status
content-type: application/json
accept: application/json

Aidbox will attempt a handshake with the service three times at 10-second intervals. If no successful response is received, the subscription will be shifted to an "errored" status. To restart the process, the subscription should be deleted and recreated

Last updated