RDC Interoperability Guide

Fetching subscription status

The subscriber can check the status of a subscription by issuing a request such as

curl -sS "https://${server}/fhir/r5/api/Subscription/42/\$status" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

Example result for an active subscription:

{
  "resourceType": "Bundle",
  "id": "482c9449-add0-4312-a6ba-07831d5ffa5b",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "SubscriptionStatus",
        "status": "active",
        "type": "query-status",
        "eventsSinceSubscriptionStart": 28,
        "subscription": {"reference": "Subscription/42"}
      }
    }
  ]
}

Example result for a failing subscription:

{
  "resourceType": "Bundle",
  "id": "e668a70c-d149-442f-bd52-d63bc567816f",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "SubscriptionStatus",
        "status": "error",
        "type": "query-status",
        "eventsSinceSubscriptionStart": 132,
        "subscription": {"reference": "Subscription/42"},
        "error": [
          {
            "coding": [{"system": "http://terminology.hl7.org/CodeSystem/subscription-error", "code": "error-response"}],
            "text": "Notification endpoint returned HTTP error code 401 UNAUTHORIZED"
          }
        ]
      }
    }
  ]
}

The subscriber may consider verifying the status of the subscription if no notifications have been received for an extended period of time, thus ensuring that no errors have occurred. However, conducting such periodic checks more frequently than once a day is discouraged.

The fields entry[0].resource.status, entry[0].resource.error[0].text and entry[0].resource.eventsSinceSubscriptionStart may be of particular interest to the subscriber.

If the value of entry[0].resource.status is error, the subscriber should attempt to fix any errors indicated by the entry[0].resource.error[0].text field and then trigger an error recovery process (described in an upcoming section).

The value in entry[0].resource.eventsSinceSubscriptionStart is essential for the recovery process. Please note that even during normal operation this value may occasionally be larger than the last notification received by the subcriber. This condition in itself does not indicate any error (as long as the value of entry[0].resource.status is active) but can be explained with a pending notification delivery.