# OHH Subscription - Open Health Hub FHIR Implementation Guide v0.1.0

* [**Table of Contents**](toc.md)
* [**Artifacts Summary**](artifacts.md)
* **OHH Subscription**

## Resource Profile: OHH Subscription 

| | |
| :--- | :--- |
| *Official URL*:https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/ohh-subscription | *Version*:0.1.0 |
| Active as of 2025-12-03 | *Computable Name*:OhhSubscription |

 
Subscriptions are used to trigger a webhook request when a resource that matches the criteria has been created or updated. 

### Scope and Usage 

Subscription can be used to get notified about changes to resources. Currently only subscription on these resources can be created:

* QuestionnaireResponse
* PlanDefinition
* CarePlan

**Usages:**

* Examples for this Profile: [Subscription/0c41aec8-286c-4a7d-8714-8137a199f46e](Subscription-0c41aec8-286c-4a7d-8714-8137a199f46e.md) and [Subscription/ExampleOhhSubscriptionWithPayload](Subscription-ExampleOhhSubscriptionWithPayload.md)
* CapabilityStatements using this Profile: [OHH FHIR API](CapabilityStatement-ohh-capability-statement.md)

You can also check for [usages in the FHIR IG Statistics](https://packages2.fhir.org/xig/ohh-fhir|current/StructureDefinition/ohh-subscription)

### Formal Views of Profile Content

 [Description of Profiles, Differentials, Snapshots and how the different presentations work](http://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#structure-definitions). 

 

Other representations of profile: [CSV](StructureDefinition-ohh-subscription.csv), [Excel](StructureDefinition-ohh-subscription.xlsx), [Schematron](StructureDefinition-ohh-subscription.sch) 

### Notes:

### Creating a Subscription

To create a Subscription to get notified about changes you’ll need to have an endpoint/URL available that can handle the notification requests.

If you want subscriptions to only be valid until a specific time, you can specify the end value of a subscription. This can be helpful if you specify an authorization token that has a limited lifetime in the headers. Note that you should keep track of expired subscriptions yourself. We won’t create new subscriptions if they expire. No notifications will be sent for this subscription after the specified timestamp. The status of the subscription will then also change to `off`.

When creating a Subscription, you can choose to also retrieve the content with the notification by setting the payload to one of the 2 allowed values [application/fhir+json, application/fhir+xml]. If you don’t want to receive the content, you’ll need to execute the request defined in the criteria to retrieve the items.

If you choose to receive notifications by setting payload, be sure to enter the correct URL to prevent data being sent to anotherserver.

#### With Payload

If you have set the payload to one of the allowed values, we’ll send the notifications with the (related) content of the subscribed resource in a Bundle of type history.

#### Headers

If your server endpoint needs specific headers in the HTTP Post request, you can add them in the `channel.header` field. This can, for example, be used when the endpoint is secured with authentication. You can, for example, add an `Authorization: Bearer <jwttoken>` value to the headers. When the notification is posted, these headers will be added to the request.

#### Supported criteria

We currently support subscriptions on PlanDefinition, QuestionnaireResponse and CarePlan:

##### PlanDefinition

You can register a Subscription on PlanDefinitions to receive notification when new programs for your client are published or if changes occur to a specific program by adding an _id query parameter to the criteria.

When the `payload` property has been set, the posted Bundle will contain the PlanDefinition that was changed/created.

##### QuestionnaireResponse

You can register a Subscription on QuestionnaireResponse to receive notification when new answers for a questionnaire have become available. Currently, you can register for notifications on all responses or on responses for a specific program/PlanDefinition. To listen for responses for a specific program, you’ll need to add the `based-on.instantiates-canonical` query parameter to your criteria and set the value to the UUID of the program you want to receive notifications for.

When the `payload` property has been set, the posted Bundle will contain the QuestionnaireResponse (with encrypted values) and the Questionnaire that corresponds to this QuestionnaireResponse. If you created the Subscription via the FHIR Viewer Gateway, the gateway will handle decryption of the QuestionnaireReponse

##### CarePlan

You can register a Subscription on CarePlan to receive notification when a CarePlan is created or updated, or when a questionnaire that is part of the CarePlan has been filled out. Currently, you can register for notifications on all CarePlans, CarePlans for a specific program/PlanDefinition, or for a specific CarePlan. To listen for CarePlans for a specific program, you’ll need to add the `instantiates-canonical` query parameter to your criteria and set the value to the UUID of the program you want to receive notifications for. When you want to receive notifications for a specific CarePlan, you can use the `_id` query parameter with the ID of the CarePlan as value.

When the `payload` property has been set, the posted Bundle will contain the CarePlan that was updated/created.



## Resource Content

```json
{
  "resourceType" : "StructureDefinition",
  "id" : "ohh-subscription",
  "url" : "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/ohh-subscription",
  "version" : "0.1.0",
  "name" : "OhhSubscription",
  "title" : "OHH Subscription Profile",
  "status" : "active",
  "date" : "2025-12-03T12:00:57+00:00",
  "publisher" : "Open Health Hub",
  "contact" : [
    {
      "name" : "Open Health Hub",
      "telecom" : [
        {
          "system" : "url",
          "value" : "https://www.openhealthhub.com"
        },
        {
          "system" : "email",
          "value" : "support@openhealthhub.com"
        }
      ]
    }
  ],
  "description" : "Subscriptions are used to trigger a webhook request when a resource that matches the criteria has been created or updated.",
  "fhirVersion" : "4.0.1",
  "mapping" : [
    {
      "identity" : "rim",
      "uri" : "http://hl7.org/v3",
      "name" : "RIM Mapping"
    },
    {
      "identity" : "w5",
      "uri" : "http://hl7.org/fhir/fivews",
      "name" : "FiveWs Pattern Mapping"
    }
  ],
  "kind" : "resource",
  "abstract" : false,
  "type" : "Subscription",
  "baseDefinition" : "http://hl7.org/fhir/StructureDefinition/Subscription",
  "derivation" : "constraint",
  "differential" : {
    "element" : [
      {
        "id" : "Subscription",
        "path" : "Subscription"
      },
      {
        "id" : "Subscription.criteria",
        "path" : "Subscription.criteria",
        "constraint" : [
          {
            "key" : "ohh-subscription-criteria",
            "severity" : "error",
            "human" : "Criteria can only be on QuestionnaireResponse, PlanDefinition, or CarePlan",
            "expression" : "matches('^(QuestionnaireResponse|PlanDefinition|CarePlan).*')",
            "source" : "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/ohh-subscription"
          }
        ]
      },
      {
        "id" : "Subscription.channel.type",
        "path" : "Subscription.channel.type",
        "fixedCode" : "rest-hook"
      }
    ]
  }
}

```
