Fetching notification events

The subscriber can fetch notification events by issuing a request such as

curl -sS "https://${server}/fhir/r5/api/Subscription/42/$events?eventsSinceNumber=10&eventsUntilNumber=12" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

The response contains the id-only notification payload, where the references that correspond to the requested event numbers are included.

Example result:

{
  "resourceType": "Bundle",
  "type": "subscription-notification",
  "entry": [
    {
      "resource": {
        "resourceType": "SubscriptionStatus",
        "status": "error",
        "type": "query-event",
        "eventsSinceSubscriptionStart": 132,
        "notificationEvent": [
          {"eventNumber": 10, "focus": {"reference": "Observation/f8c0f4bd"}},
          {"eventNumber": 11, "focus": {"reference": "Observation/ba910bb3"}},
          {"eventNumber": 12, "focus": {"reference": "Observation/78d13ebe"}}
        ],
        "subscription": {
          "reference": "Subscription/42"
        }
      }
    }
  ]
}

The range of events is determined by the eventsSinceNumber and eventsUntilNumber parameters but the results are limited to 100 events per request.

Additionally, it is possible to include the content query parameter in order to change the content of the returned payload. By default, the content is id-only, but in this endpoint, it is possible to request full-resource content by adding &content=full-resource to the request URL. Notice that when creating the subscription, the content field can only be set to id-only or empty, but when fetching events, the subscriber can request either id-only or full-resource content because to access the /$events endpoint, the subscriber must already be authenticated and authorized to access the resources.

⚠️ Note: The behavior of the $events operation without the eventsSinceNumber and eventsUntilNumber parameters is undefined and subject to change. For a well-defined behavior, clients need to explicitly define the requested range of events.

Please note that under the normal operation of a subscription with id-only content, it should not be necessary for a subscriber to fetch events, as they are automatically delivered to the notification endpoint. The $events endpoint is only needed for error recovery.