Subscription API

While FHIR topic-based subscriptions are functional, they will no longer receive active development or new features. For enhanced capabilities and ongoing support, please use Aidbox topic-based subscriptions. This newer implementation offers improved performance, flexibility, and will continue to be developed to meet future needs.

Create Subscription - POST /fhir/Subscription

Creates a new subscription. Takes params depending on the current version of FHIR used in Aidbox.

The R4B Subscriptions resource uses FHIR extension fields that should be written according to the specification. You should also add the subscription backport profile URL to your resource's meta.profile field.

Parameters

R4B

Parameter	Type	Required	Description
meta	object
meta.profile	string[]		Extension URL: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription
id	string		Identifier of the resource. Will be auto-generated if not provided.
reason	string		Human readable reason for subscription.
criteria	string		Canonical URL for the topic used to generate events. Example: http://aidbox.app/SubscriptionTopic/patient-test-1
criteria.extension: filterCriteria	string[]		The filters applied to events in the following format: [resourceType.]filterParameter=[modifier]value filterParameter above should be one of the filter names defined by the relevant SubscriptionTopic (canFilterBy.filterParameter field). resourceType and modifiers should be the ones allowed in the corresponding canFilterBy.filterParameter of the relevant SubscriptionTopic as well. resourceType is only necessary for disambiguation. When multiple filters are applied, it evaluates to true if all the conditions applicable to that resource are met; otherwise, it returns false (i.e., logical AND). Example: patient-birth=gt2005-01-01T01:00:00Z
channel.extension: heartbeatPeriod	integer		Interval in seconds to send 'heartbeat' notification. Default value: 120
channel.extension: timeout	integer		Timeout in seconds to attempt notification delivery. Default value: 30
channel.extension: maxCount	integer		Maximum number of triggering resources included in notification bundles. Default value: 10
channel.type	string		The type of channel to send notifications on. Supported values: rest-hook
channel.header	string[]		Additional headers/information to send as part of the notification. For the rest-hook channel type, this will be HTTP request headers. Example: ["random-header: secret123"]
channel.endpoint	string		The URL that describes the actual end-point to send messages to. Example: https://my.app/endpoint
channel.payload	string		MIME-type to send, or omit for no payload. Supported values: application/fhir+json
channel.payload.extension: content	string		Notification content level. Supported values: empty, id-only, full-resource. Default value: empty
status	string		Status of the subscription. On the creation of this resource, the status is always requested and other values will be ignored.
end	string		When to automatically delete the subscription.

R5

Parameter	Type	Required	Description
id	string		Identifier of the resource. Default value: generated
topic	string		Url reference to subscription topic. Example: http://aidbox.app/SubscriptionTopic/patient-test-1
status	string		Status of the subscription. On the creation of this resource, the status is always requested and other values will be ignored.
reason	string		Human readable reason for Subscription.
filterBy	object[]		Filters applied to the resources that would be included in the notification. When multiple filters are applied to one resource type, evaluates to true if all the conditions are met.
filterBy.resourceType	string		Resource for this Subscription filter. Example: Patient
filterBy.filterParameter	string		Filter label defined in SubscriptionTopic.
filterBy.value	string		Literal value or resource path.
filterBy.comparator	string		Comparator applied to this filter parameter. Should be allowed in SubscriptionTopic resource. Supported values: eq, gt, lt, ge, le.
filterBy.modifier	string		Modifier applied to this filter parameter. Should be allowed in SubscriptionTopic resource. Supported values: temporary not supported.
channelType	object		The type of channel to send notifications on.
channelType.system	string		http://terminology.hl7.org/CodeSystem/subscription-channel-type
channelType.code	string		The type of channel to send notifications on. Supported values: rest-hook
endpoint	string		The url that describes the actual end-point to send notifications to.
heartbeatPeriod	integer		Interval in seconds to send 'heartbeat' notification.
parameter	object[]		Additional headers/information to send as part of the notification. For the rest-hook channel type, this will be HTTP request headers.
parameter.name	string		Example: "random-header".
parameter.value	string		Example: "secret123".
timeout	integer		Timeout in seconds to attempt notification delivery.
content	string		How much of the resource content to deliver in the notification payload. The choices are an empty payload, only the resource id, or the full resource content. Supported values: empty, id-only, full-resource
maxCount	integer		Maximum number of events that can be combined in a single notification.
end	string		When to automatically delete the subscription.

Example

Request

POST /fhir/Subscription
content-type: text/yaml
accept: text/yaml

meta:
  profile:
  - http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription
criteria: http://aidbox.app/SubscriptionTopic/patient-test-1
channel:
  extension:
  - url: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period
    valueUnsignedInt: 60
  - url: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout
    valueUnsignedInt: 1
  - url: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count
    valuePositiveInt: 2
  type: rest-hook
  endpoint: http://localhost:27193/patient-test-1
  payload: application/fhir+json
  _payload:
    extension:
    - url: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content
      valueCode: id-only
resourceType: Subscription
reason: R4/B Test Topic-Based Subscription for Patient resources
status: active
id: subscription-patient-test-1
end: '2020-12-31T12:00:00Z'

Response

Status: 201

meta:
  profile:
    - >-
      http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription
  lastUpdated: '2023-09-06T07:03:26.763869Z'
  versionId: '735'
  extension:
    - url: http://example.com/createdat
      valueInstant: '2023-09-06T07:03:26.763869Z'
criteria: http://aidbox.app/SubscriptionTopic/patient-test-1
channel:
  type: rest-hook
  payload: application/fhir+json
  extension:
    - url: >-
        http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout
      valueUnsignedInt: 1
    - url: >-
        http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count
      valuePositiveInt: 2
    - url: >-
        http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period
      valueUnsignedInt: 60
  _payload:
    extension:
      - url: >-
          http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content
        valueCode: id-only
  endpoint: http://localhost:27193/patient-test-1
resourceType: Subscription
reason: R4/B Test Topic-Based Subscription for Patient resources
status: requested
id: subscription-patient-test-1
end: '2020-12-31T12:00:00Z'

Subscription Status - GET /fhir/Subscription/[id]/$status

This operation is used to get the current status information about a topic-based Subscription.

Returns FHIR bundle where the SubscriptionStatus resource is the only entry element.

Example

Request

GET /fhir/Subscription/subscription-patient-test-1/$status
content-type: text/yaml
accept: text/yaml

Response

Status: 200

resourceType: Bundle
type: history
timestamp: '2023-09-06T07:25:19.631905713Z'
entry:
  - resource:
      resourceType: SubscriptionStatus
      status: active
      type: query-status
      eventsSinceSubscriptionStart: 0
      subscription:
        reference: http://aidbox.app/fhir/Subscription/subscription-patient-test-1
      topic: http://aidbox.app/SubscriptionTopic/patient-test-1

Subscription Events - GET /fhir/Subscription/[id]/$events

This operation is used to search for and get notifications that have been previously triggered by a topic-based Subscription.

Returns FHIR bundle where the SubscriptionStatus resource is the first entry element, and triggered events are the rest.

Parameters

Parameter	Type	required	Description
eventsSinceNumber	integer		The starting event number, inclusive of this event (lower bound).
eventsUntilNumber	integer		The ending event number, inclusive of this event (upper bound).

If the params above are not provided, returns the latest 20 events.

Example

Request

GET /fhir/Subscription/subscription-patient-test-1/$events
content-type: text/yaml
accept: text/yaml

Response

Status: 200

resourceType: Bundle
type: history
timestamp: '2023-09-06T07:40:59.527416959Z'
entry:
  - resource:
      resourceType: SubscriptionStatus
      status: active
      type: query-event
      eventsSinceSubscriptionStart: 19
      subscription:
        reference: http://aidbox.app/fhir/Subscription/subscription-patient-test-1
      topic: http://aidbox.app/SubscriptionTopic/patient-test-1
      notificationEvent:
        - eventNumber: 1
          timestamp: '2023-09-04 10:38:43.020984+03'
          focus:
            reference: >-
              http://aidbox.app/fhir/Patient/c868fc6f-0631-43cc-940a-c43177fe6567
        - eventNumber: 2
          timestamp: '2023-09-04 10:38:44.382835+03'
          focus:
            reference: >-
              http://aidbox.app/fhir/Patient/fe174a4e-e3ba-4d75-98b6-17fea275dda1
        - eventNumber: 3
          timestamp: '2023-09-04 10:38:44.888717+03'
          focus:
            reference: >-
              http://aidbox.app/fhir/Patient/98485698-083d-4659-8869-b4f0d87734ac
        - eventNumber: 4
          timestamp: '2023-09-04 10:38:45.031019+03'
          focus:
            reference: >-
              http://aidbox.app/fhir/Patient/cc95822b-ed0d-4e6a-ad48-358d029d8c61
        - eventNumber: 5
          timestamp: '2023-09-04 10:38:45.171641+03'
          focus:
            reference: >-
              http://aidbox.app/fhir/Patient/36df7d8f-1a03-4073-8435-6741cdba90e9
  - fullUrl: http://aidbox.app/fhir/Patient/c868fc6f-0631-43cc-940a-c43177fe6567
    request:
      method: POST
      url: Patient/c868fc6f-0631-43cc-940a-c43177fe6567
    response:
      status: '201'
  - fullUrl: http://aidbox.app/fhir/Patient/fe174a4e-e3ba-4d75-98b6-17fea275dda1
    request:
      method: POST
      url: Patient/fe174a4e-e3ba-4d75-98b6-17fea275dda1
    response:
      status: '201'
  - fullUrl: http://aidbox.app/fhir/Patient/98485698-083d-4659-8869-b4f0d87734ac
    request:
      method: POST
      url: Patient/98485698-083d-4659-8869-b4f0d87734ac
    response:
      status: '201'
  - fullUrl: http://aidbox.app/fhir/Patient/cc95822b-ed0d-4e6a-ad48-358d029d8c61
    request:
      method: POST
      url: Patient/cc95822b-ed0d-4e6a-ad48-358d029d8c61
    response:
      status: '201'
  - fullUrl: http://aidbox.app/fhir/Patient/36df7d8f-1a03-4073-8435-6741cdba90e9
    request:
      method: POST
      url: Patient/36df7d8f-1a03-4073-8435-6741cdba90e9
    response:
      status: '201'

Subscription and events RPC

Returns all data about subscription and its events.

RPC endpoint: fhir.topic-based-subscription/get-subscription-by-id

Parameters

Parameter	Type	Description
id	string	id of subscription
events-limit	int	Limit of events to fetch. Default is 10.

Example

Request

POST /rpc

method: fhir.topic-based-subscription/get-subscription-by-id
params:
  id: subscription-patient-test-1

Response

result:
  resource:
    maxCount: 2
    service-definition:
      # ... definition from zen
    content: id-only
    events:
      - body:
          focusResource:
            id: >-
              pat4
            meta:
              extension:
                - url: ex:createdAt
                  valueInstant: '2024-10-01T10:42:12.204409Z'
              versionId: '164'
              lastUpdated: '2024-10-01T10:42:12.204409Z'
            gender: male
            resourceType: Patient
        error: no-response
        headers:
          values:
            first-family-name: null
            prev-first-family-name: null
            first-family-name-alternative: null
          focusId: pat4
          timestamp: '2024-10-01T10:42:12.206127Z'
          interaction: create
          focusResourceType: Patient
        lsn: 0/46F6680
        seq_num: 4
        type: handshake
        eventNumber: 0
    topic: http://aidbox.app/SubscriptionTopic/patient-test-1
    resourceType: Subscription
    reason: R4/B Test Topic-Based Subscription for Patient resources
    heartbeatPeriod: 60
    status: active
    id: subscription-patient-test-1
    topic-id: c78aab4508bf90b63bcc18b70e61bbf2
    contentType: application/fhir+json
    timeout: 1
    filterBy: []
    endpoint: http://localhost:27193/patient-test-1
    parameter: []
    channelType:
      code: rest-hook

Delete Subscription - DELETE /fhir/Subscription/[id]

Delete Subscription resource.

Parameter	Type	Description
resource	object	Deleted Subscription resource.

Example

Request

DELETE /fhir/Subscription/subscription-patient-test-1

Response

Status: 200

{
 "meta": {
  "profile": [
   "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription"
  ],
  "lastUpdated": "2023-09-06T07:15:30.481730Z",
  "versionId": "746",
  "extension": [
   {
    "url": "http://example.com/createdat",
    "valueInstant": "2023-09-06T07:15:30.481730Z"
   }
  ]
 },
 "criteria": "http://aidbox.app/SubscriptionTopic/patient-test-1",
 "channel": {
  "type": "rest-hook",
  "payload": "application/fhir+json",
  "extension": [
   {
    "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
    "valueUnsignedInt": 1
   },
   {
    "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
    "valuePositiveInt": 2
   },
   {
    "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
    "valueUnsignedInt": 60
   }
  ],
  "_payload": {
   "extension": [
    {
     "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
     "valueCode": "id-only"
    }
   ]
  },
  "endpoint": "http://localhost:27193/patient-test-1"
 },
 "resourceType": "Subscription",
 "reason": "R4/B Test Topic-Based Subscription for Patient resources",
 "status": "active",
 "id": "subscription-patient-test-1",
 "end": "2020-12-31T12:00:00Z"
}