Aidbox configuration
API
Profiling and validation
Terminology
FHIR Implementation Guides
App development guides
Security & Access Control
Multibox
Integrations
Tools
Aidbox Subscriptions
Aidbox subscriptions module is a way to subscribe and get notifications about updating resources on the server. It is a common denominator of FHIR R4/R5 subscriptions specification with some extensions.
This module introduces two new resources into Aidbox:
- SubsSubscription — meta-resource which binds events (create/update/delete resource) with a communication channel through which subscriber is notified about changes.
- SubsNotification — resource which represents notification with its status (sent or not).
Aidbox doesn't delete SubsNotification resources by itself. The simple way to implement a retention policy is to create a cron job. Let us know if there is a more clear way.
Your service can register subscription by POST SubsSubscription resource:
1
POST /SubsSubscription
2
Accept: text/yaml
3
Content-Type: text/yaml
4
5
id: myservice-subs
6
7
status: active # 'active' is default, if 'off' - subscription is disabled
8
# Subscribe to all changes of Patient and Person resources
9
trigger:
10
# resource type
11
Patient:
12
event: ['all'] # can be all | create | update | delete
13
# collection of filters
14
filter:
15
# use matcho engine to filter resources
16
- matcho: { active: true }
17
Person:
18
event: ['all']
19
20
# how to deliver notifications
21
channel:
22
type: rest-hook
23
# url to send hook
24
endpoint: https://myservice/subs/patient
25
# headers to add to request (for consistency use lowercase names)
26
headers:
27
Authorization: Bearer <......>
28
# recomended timeout for web hook in ms, server may use it's own
29
timeout: 1000
30
payload:
31
# this is default value, you can use id-only
32
content: full-resource # full-resource | id-only
33
# means aidbox format, or fhir+json to get resource in FHIR format
34
contentType: json # json | fhir+json
35
36
Copied!
Trigger format
Subscription.trigger is a key-value object, where key is resource type and each value can contain a collection of events (values can be 'all', 'create', 'update', 'delete') and .filter collection. For now filter support matcho engine (FHIRPath and FHIR Search filters are coming soon):
1
trigger:
2
Encounter:
3
filter:
4
- matcho: { class: {code: 'inpatient'} }
5
- matcho: { type: { coding: [{code: 'Sometype'}]}
Copied!
Filter matches if at least one of item in the collection matches, i.e. collection has
or semantic.Protocol
After you registered subscription, Aidbox sends on channel.endpoint
handshake notification in json format. It's good if your service responds with status: 2001
POST https://myservice/subs/patient
2
Content-Type: application/json
3
... channel.headers ...
4
5
{
6
"type": "handshake",
7
"subscription": { ...SubsSubscription resource content... }
8
}
Copied!
On every trigger event Aidbox will send a notification to your service endpoint. Your service has to respond with
status: 200 and optional json body.1
POST https://myservice/subs/patient
2
Content-Type: application/json
3
... channel.headers ...
4
5
{
6
"id": <unique-id>,
7
"type": "notification",
8
"event": "create", # update | delete
9
"resource": {"resourceType": "Patient", ..... }
10
}
Copied!
Results of all notifications are logged into SubsNotification resource:
1
GET /SubsNotification
2
Accept: text/yaml
3
4
---
5
id: <unique-id>
6
subscription: { id: 'myservice-subs', resourceType: SubsSubscription }
7
duration: 23 # hook duration in ms
8
status: success # fail
9
notification: <notification content>
10
response: <response content if present>
Copied!
SubsSubscription/<id>/$handshake
You can force a handshake notification for the specific subscription with:
1
POST /SubsSubscription/<sub-id>/$handshake
2
Accept: text/yaml
3
4
# response
5
6
resourceType: SubsNotification
7
notification:
8
type: handshake
9
debug: true
10
subscription: ...
11
subscription: {resourceType: SubsSubscription, id: <sub-id>}
12
duration: 1
13
status: failed
14
error: {message: Connection refused}
Copied!
SubsSubscription/<id>/$debug
To debug subscription notifications, you can send debug messages with:
1
POST /SubsSubscription/<sub-id>/$debug
2
Accept: text/yaml
3
Content-Type: text/yaml
4
5
id: notif-id
6
event: create
7
type: notification
8
resource:
9
resourceType: Patient
10
id: pt-1
11
12
# response
13
14
resourceType: SubsNotification
15
notification:
16
type: notification
17
resource: {id: pt-1, resourceType: Patient}
18
debug: true
19
subscription: {resourceType: SubsSubscription, id: <sub-id>}
20
duration: 1
21
status: failed
22
error: {message: Connection refused}
Copied!
SubsNotification/$notify (not implemented yet)
Or you can send a list of notifications by providing a list of search params:
1
POST /SubsNotification/$notify?_id=id-1,id-2,id-3
Copied!
SubsNotification/<id>/$notify
You can resend the specific notification with
1
POST /SubsNotification/<notif-id>/$notify
2
Accept: text/yaml
3
4
# response
5
6
status: ...
7
duration: ...
8
notification: ....
9
response: ...
Copied!
/subs/webhook (not implemented yet)
You can subscribe one instance of Aidbox to notifications from another instance and replicate data between boxes by using
/subs/webhook/<source-id> endpoint:1
POST /SubsSubscription
2
Accept: text/yaml
3
Content-Type: text/yaml
4
5
id: box-replication
6
status: active
7
trigger:
8
Patient: { event: ['all'] }
9
channel:
10
type: rest-hook
11
endpoint: <other-box-url>/subs/webhook/box-1
12
headers:
13
Authorization: Bearer <token>
14
Copied!
Last modified 1mo ago