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
.meta.profile field.
Parameters R4B R5
Parameter Type Required Description meta object false meta.profile string[] true Extension URL:http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription id string false Identifier of the resource. Will be auto-generated if not provided. reason string false Human readable reason for subscription. criteria string true Canonical URL for the topic used to generate events.
Example: http://aidbox.app/SubscriptionTopic/patient-test-1
criteria.extension:
filterCriteria
string[] false 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 false Interval in seconds to send 'heartbeat' notification.
Default value: 120
channel.extension:
timeout
integer false Timeout in seconds to attempt notification delivery.
Default value: 30
channel.extension:
maxCount
integer false Maximum number of triggering resources included in notification bundles.
Default value: 10
channel .typestring true The type of channel to send notifications on.Supported values: rest-hook channel .headerstring[] false 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 .endpointstring false The URL that describes the actual end-point to send messages to.
Example: https://my.app/endpoint
channel .payloadstring false MIME-type to send, or omit for no payload.Supported values: application/fhir+json channel.payload.extension:
content
string false Notification content level .
Supported values: empty, id-only, full-resource.
Default value: empty
status string false Status of the subscription.
On the creation of this resource, the status is always requested and other values will be ignored.
end string false When to automatically delete the subscription.
Parameter Type Required Description id string false Identifier of the resource.
Default value: generated
topic string true Url reference to subscription topic.
Example: http://aidbox.app/SubscriptionTopic/patient-test-1
status string false Status of the subscription.
On the creation of this resource, the status is always requested and other values will be ignored.
reason string false Human readable reason for Subscription. filterBy object[] false Filters applied to the resources that would be included in the notification. filterBy .resourceTypestring false Resource for this Subscription filter.Example: Patient filterBy .filterParameterstring false Filter label defined in SubscriptionTopic. filterBy .valuestring false Literal value or resource path. filterBy .comparatorstring false Comparator applied to this filter parameter. Should be allowed in SubscriptionTopic resource.Supported values: eq, gt, lt, ge, le. filterBy .modifierstring false Modifier applied to this filter parameter. Should be allowed in SubscriptionTopic resource.Supported values: temporary not supported. channelType object true The type of channel to send notifications on. channelType .systemstring false http://terminology.hl7.org/CodeSystem/subscription-channel-type channelType .codestring false The type of channel to send notifications on.Supported values: rest-hook endpoint string false The url that describes the actual end-point to send notifications to. heartbeatPeriod integer false Interval in seconds to send 'heartbeat' notification. parameter object[] false Additional headers/information to send as part of the notification. For the rest-hook channel type, this will be HTTP request headers. parameter .namestring false Example: "random-header". parameter .valuestring false Example: "secret123". timeout integer false Timeout in seconds to attempt notification delivery. content string false 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 false Maximum number of events that can be combined in a single notification. end string false When to automatically delete the subscription.
Example Request Response
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'
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 Response
GET /fhir/Subscription/subscription-patient-test-1/$status
content-type: text/yaml
accept: text/yaml
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 false The starting event number, inclusive of this event (lower bound). eventsUntilNumber integer false The ending event number, inclusive of this event (upper bound).
If the params above are not provided, returns the latest 20 events.
Example Request Response
GET /fhir/Subscription/subscription-patient-test-1/$events
content-type: text/yaml
accept: text/yaml
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 Response
POST /rpc
method: fhir.topic-based-subscription/get-subscription-by-id
params:
id: subscription-patient-test-1
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 Response
DELETE /fhir/Subscription/subscription-patient-test-1
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"
}