Interaction: Create Subscription

The Create Subscription interaction creates a subscription to a specified event, enabling the subscriber to receive notifications when the event occurs.

Specification

This specification is based on the FHIR R5 Backport Create operations.

Usage

Subscription Create Request

Client creates and submits a request to the FHIR server to express interest to subscribe for notifications about changes to specific resources. Client use HTTP POST method to submit subscritpion request in the following manner

POST [base]/Subscription HTTP/1.1

Host: example.com

Content-Type: application/fhir+json

where the HTTP Body contains a FHIR R5 Backport Subscription resource, conformant to Profile: Subscription

Mandatory elements

When creating a Subscription resource, the following elements are mandatory:

Element Description
status Defines the lifecycle status of the subscription (e.g., requested, active, error).
criteria References a canonical URL for the topic used to generate resource that defines the events of interest.
criteria.filterCriteria Filtering critiera applied to events.
channel.Type Specifies the notification channel type (e.g., rest-hook, websocket, email).
endpoint (if applicable) The URL or target for delivering notifications (required for rest-hook).
reason Describes why the subscription was created.
payload.content 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.

Interaction Sequence Diagram

Sub_Create

Example Create Subscription Interaction

Request Message:

HTTP Method:

POST

Headers:

Content-Type: application/fhir+json

Address:

[base]/Subscription/

Response message body:

{
    "resourceType": "Subscription",
    "id": "subscription-admission",
    "meta": {
        "profile":  [
            "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription"
        ]
    },
    "text": {
        "status": "generated",
        --- We have skipped the narrative for better readability of the resource ---
    },
    "status": "active",
    "end": "2020-12-31T12:00:00Z",
    "reason": "R4/B Example Topic-Based Subscription for Patient Admission",
    "criteria": "http://hl7.org/SubscriptionTopic/admission",
    "_criteria": {
        "extension":  [
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
                "valueString": "Encounter?patient=Patient/123"
            }
        ]
    },
    "channel": {
        "extension":  [
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
                "valueUnsignedInt": 86400
            },
            {
                "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": 20
            }
        ],
        "type": "rest-hook",
        "endpoint": "https://example.org/Endpoints/d7dcc004-808d-452b-8030-3a3a13cd871d",
        "payload": "application/fhir+json",
        "_payload": {
            "extension":  [
                {
                    "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
                    "valueCode": "id-only"
                }
            ]
        }
    }
}

Expected Behaviour

Case Scenario Description HTTP Status Code Response Payload
1 A valid Subscription is submitted, accepted, and created in the repository HTTP 200 Created. Returns the created resource.
2 The subscribtion has been received but is being processed asynchronously HTTP 202 Accepted.
3 The submitted Subscription cannot be validated as it does not conform to the specification HTTP 400 Bad Request. Returns an OperationOutcome resource indicating an issue. The client must fix the request and try again.
4 Subsciprtion API validates the request but cannot return a valid response due to internal issues. HTTP 500 Internal Server Error. Returns an OperationOutcome resource indicating an issue.

Supported Profiles

Profile Name URL
Backport Subscription R4/B Topic-Based Subscription