--- description: FHIR Subscriptions Aidbox Topic-Based Subscriptions for real-time notifications and event-driven workflows. --- # Aidbox Topic-Based Subscriptions {% hint style="info" %} This functionality is available in Aidbox versions 2409 and later and requires [FHIR Schema](../profiling-and-validation/fhir-schema-validator/) validation engine to be [enabled](../profiling-and-validation/fhir-schema-validator/). {% endhint %} ### Overview This feature enables dynamic subscriptions to changes in FHIR resources, allowing users/systems to receive notifications through [multiple channels](#currently-supported-channels). {% hint style="info" %} **Looking for FHIR-standard Subscriptions?** If you need external systems or clients to create their own subscriptions using standard FHIR `Subscription` resources, see [FHIR Topic-Based Subscriptions](fhir-topic-based-subscriptions.md). FHIR Topic-Based Subscriptions are built on top of the mechanism described on this page. Aidbox Topic Destinations are best for server-side integrations managed by administrators. {% endhint %}
Architecture diagram showing topic-based subscriptions flow
For an application example, refer to [Aidbox Subscriptions & Kafka AidboxTopicDestination](https://github.com/Aidbox/examples/tree/main/aidbox-features/aidbox-subscriptions-to-kafka) ## Key Components * **`AidboxSubscriptionTopic`** is a custom Aidbox resource modeled after the [FHIR R6 SubscriptionTopic](https://build.fhir.org/subscriptiontopic.html) resource. The resource allows defining a set of events that clients can subscribe to, such as changes in specific resources. * **`AidboxTopicDestination`** is a custom Aidbox resource that defines where and how the notifications triggered by an `AidboxSubscriptionTopic` should be sent. This resource offers flexibility in specifying various types of destinations. And is considered as a system configuration resource. * **`AidboxSubscriptionStatus`** is a custom Aidbox resource which describes the notifications: what messages stored in the bundle, source and destination. ## Currently supported channels {% cards %} {% card icon="assets/brand-icons/webhook.svg" title="Webhook" href="../../tutorials/subscriptions-tutorials/webhook-aidboxtopicdestination.md" %} Send FHIR resource events to HTTP webhooks with retry logic and batch support. {% endcard %} {% card icon="assets/brand-icons/pubsub.svg" title="GCP Pub/Sub" href="../../tutorials/subscriptions-tutorials/gcp-pub-sub-aidboxtopicdestination.md" %} Stream FHIR resource events to Google Cloud Pub/Sub with guaranteed delivery. {% endcard %} {% card icon="assets/brand-icons/kafka.svg" title="Kafka" href="../../tutorials/subscriptions-tutorials/kafka-aidboxtopicdestination.md" %} Stream FHIR resource events to Apache Kafka with best-effort or at-least-once delivery. {% endcard %} {% card icon="assets/brand-icons/clickhouse.svg" title="ClickHouse" href="../../tutorials/subscriptions-tutorials/clickhouse-aidboxtopicdestination.md" %} Export FHIR resources to ClickHouse with SQL-on-FHIR ViewDefinitions for real-time reporting. {% endcard %} {% card icon="assets/brand-icons/bigquery.svg" title="BigQuery" href="../../tutorials/subscriptions-tutorials/bigquery-aidboxtopicdestination.md" %} Export FHIR resources to Google BigQuery with SQL-on-FHIR ViewDefinitions. {% endcard %} {% card icon="assets/brand-icons/nats.avif" title="NATS" href="../../tutorials/subscriptions-tutorials/aidboxtopicsubscription-nats-tutorial.md" %} Integrate Aidbox topic-based subscriptions with NATS and NATS JetStream. {% endcard %} {% card icon="assets/brand-icons/rabbitmq.svg" title="RabbitMQ" href="../../tutorials/subscriptions-tutorials/rabbitmq-tutorial.md" %} Connect Aidbox subscriptions to RabbitMQ over AMQP for real-time FHIR events. {% endcard %} {% card icon="assets/brand-icons/activemq.avif" title="ActiveMQ" href="../../tutorials/subscriptions-tutorials/activemq-tutorial.md" %} Integrate Aidbox subscriptions with ActiveMQ using AMQP 1.0 for event streaming. {% endcard %} {% card icon="assets/brand-icons/aws.svg" title="AWS EventBridge" href="../../tutorials/subscriptions-tutorials/aws-eventbridge-aidboxtopicdestination.md" %} Route FHIR resource events to AWS EventBridge for serverless processing. {% endcard %} {% card icon="assets/brand-icons/aws.svg" title="AWS SNS" href="../../tutorials/subscriptions-tutorials/aidboxtopicsubscription-sns-tutorial.md" %} Stream FHIR resource events to AWS SNS for pub/sub messaging and fan-out notifications. {% endcard %} {% card icon="assets/brand-icons/databricks.svg" title="Data Lakehouse (Databricks)" href="../../tutorials/subscriptions-tutorials/data-lakehouse-aidboxtopicdestination.md" %} Export FHIR resources to Databricks Unity Catalog managed Delta tables. {% endcard %} {% endcards %} ## AidboxSubscriptionTopic The `AidboxSubscriptionTopic` resource describes the data sources for subscriptions. It allows clients to subscribe to events in Aidbox and filter them using user-defined triggers, which are specified by the `trigger` element. Supported properties:
PropertyTypeDescription
resource *uriResource (reference to definition) for this trigger definition. It is binding to All Resource Types.
supportedInteractioncodecreate | update | delete
fhirPathCriteriastringFHIRPath based trigger rule. FHIRPath criteria are evaluated only within the context of the current resource. Supports %current and %previous variables for comparing resource states during updates.
descriptionstringText representation of the event trigger.
\* required. {% hint style="info" %} [`PATCH`](../../api/rest-api/crud/patch.md) requests (merge-patch, JSON Patch, and FHIRPath Patch) map to the `update` interaction — a topic with `supportedInteraction: update` fires for PATCH-originated changes too. A no-op patch (one that doesn't change the resource) does not fire the event. {% endhint %} #### Create `AidboxSubscriptionTopic` resource ```json POST /fhir/AidboxSubscriptionTopic content-type: application/json accept: application/json { "resourceType": "AidboxSubscriptionTopic", "url": "http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic", "status": "active", "trigger": [ { "resource": "QuestionnaireResponse", "fhirPathCriteria": "status = 'completed' or status = 'amended'" } ] } ``` ## AidboxTopicDestination The `AidboxTopicDestination` resource is used to define channel configurations for processing subscription data. {% hint style="info" %} Sensitive Kafka parameters like `saslJaasConfig` and `sslKeystoreKey` support [external secrets](../../configuration/secret-files.md) — store credentials outside the database using vault config files. {% endhint %} #### Create a TopicDestination To start processing subscription data, create a `AidboxTopicDestination` resource with a reference to the `AidboxSubscriptionTopic`. Examples of `AidboxTopicDestination` resources can be found in sub-sections. #### Stop subscription data processing To stop processing subscription data, delete the `AidboxTopicDestination` resource. #### Updating a TopicDestination {% hint style="warning" %} `AidboxTopicDestination` is **immutable** — `PUT` and `PATCH` requests return `405 Method Not Allowed`. The same restriction applies inside transaction and batch bundles, including [init bundles](../../configuration/init-bundle.md). This is by design: an `AidboxTopicDestination` owns long-lived resources (Kafka producers, webhook clients, GCP Pub/Sub sessions, etc.) that cannot be hot-reloaded. {% endhint %} To change a destination's configuration, `DELETE` the existing resource and `POST` a new one. In an init bundle, use a `batch` bundle so the `DELETE` succeeds when the resource does not yet exist (returns `204`): ```json { "resourceType": "Bundle", "type": "batch", "entry": [ { "request": { "method": "DELETE", "url": "AidboxTopicDestination/" } }, { "resource": { "resourceType": "AidboxTopicDestination", "id": "", "...": "..." }, "request": { "method": "POST", "url": "AidboxTopicDestination" } } ] } ``` `AidboxSubscriptionTopic` does support `PUT`, so only the destination resource needs the DELETE+POST pattern. #### Status (`$status`) and HA deployments Each kind-specific tutorial (e.g. [webhook](../../tutorials/subscriptions-tutorials/webhook-aidboxtopicdestination.md#status-introspection), [Kafka](../../tutorials/subscriptions-tutorials/kafka-aidboxtopicdestination.md)) describes the [`$status`](../../tutorials/subscriptions-tutorials/webhook-aidboxtopicdestination.md#status-introspection) operation. One detail applies to every destination kind: * **`messagesDelivered`, `messageBatchesDelivered`, `messagesDeliveryAttempts`, `messageBatchesDeliveryAttempts`, `messagesInProcess`, `lastErrorDetail`, and `startTimestamp` are per-replica** and held in memory. They reset on Aidbox restart and are not summed across replicas. * **`messagesQueued` is computed from the database** and is consistent across replicas. In a [highly available](../../deployment-and-maintenance/deploy-aidbox/run-aidbox-in-kubernetes/highly-available-aidbox.md) deployment, calling `$status` through a load balancer returns whichever replica answered. To get cluster-wide totals, query each pod directly and sum the in-memory counters — see [Counter semantics](../../tutorials/subscriptions-tutorials/webhook-aidboxtopicdestination.md#counter-semantics) for the full breakdown. #### AidboxTopicDestination Profile Ensure that the resource metadata contains the kind-specific `AidboxTopicDestination` profile. #### **Elements**
Property Type Description
status code active - the only possible value for now. Expected to be expanded.
topic * string Url of AidboxSubscriptionTopic resource.
kind * code Defines the destination for sending notifications. Supported values: kafka-at-least-once, kafka-best-effort, webhook-at-least-once, gcp-pubsub-at-least-once, nats-at-least-once, nats-best-effort, amqp-at-least-once, aws-eventbridge, aws-sns, clickhouse, clickhouse-at-least-once, bigquery-at-least-once, data-lakehouse-at-least-once
parameter * FHIR parameters Defines the destination parameters for sending notifications. Parameters are restricted by profiles for each destination.
content Subscription payload content full-resource | id-only | empty
full-resource is the default value.
includeEntryAction boolean When true, each Bundle.entry includes the bundle-entryActionCode extension indicating the CRUD action (create | update | delete) that triggered the notification. Default: false.
includeVersionId boolean When true, each Bundle.entry includes the bundle-entryVersionId extension containing the resource's meta.versionId at the time of the notification. Default: false.
includeVersionIdInFocusReference boolean When true, the focus.reference in each notificationEvent of the AidboxSubscriptionStatus includes the version history path (e.g. Patient/123/_history/5 instead of Patient/123). Default: false.
enableLogging boolean When true, AidboxSubscriptionStatus is logged after each delivery attempt. On failure, the logged status includes an error array. Useful for debugging and monitoring topic destination delivery (supported since the 2604 release). Default: false.
logLevel code The log level used when enableLogging is true. Supported values: error | warn | info | debug | trace. Must be equal to or higher than the system-wide log level setting, otherwise messages will be filtered out (supported since the 2604 release). Default: info.
\* required. ## Organization-based hierarchical filtering {% hint style="warning" %} Organization-based hierarchical filtering is available starting from version 2509. {% endhint %} Both `AidboxSubscriptionTopic` and `AidboxTopicDestination` support [organization-based hierarchical access control](../../access-control/authorization/scoped-api/organization-based-hierarchical-access-control.md). ### How it works The filtering mechanism uses organization extensions and works as consecutive filters: 1. **Use organization extension**: In organizational-based access control, both events (resources) and subscription resources (`AidboxSubscriptionTopic` and `AidboxTopicDestination`) are automatically marked with [organization extensions](../../access-control/authorization/scoped-api/organization-based-hierarchical-access-control.md#try-org-bac) when created through organization-specific APIs (`/Organization//fhir/...`). 2. **Consecutive filtering**: The filters work in sequence - first the topic filter is applied, then the destination filter. 3. **Resources without organization extension**: If topic/destination resources are created without organization extension, they completely ignore organization information and work as before. All events will be caught by the topic if triggered (regardless of whether the event has organization extension or not). 4. **Resources with organization extension**: * **Events without organization extension**: Will always be skipped * **Events with organization extension**: * ✅ **Caught**: If the event organization is under or equal to the topic/destination organization in the hierarchy * ❌ **Skipped**: If the event organization is above or unrelated to the topic/destination organization ### Examples #### Example 1: Organization hierarchy with event filtering Consider an organization structure where `Organization B` is part of `Organization A`. The diagram below shows how events flow through the subscription system with hierarchical filtering: ``` ┌─────────────────────┐ ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ ┌─────────────────┐ │Organization Hierarch│ │ Event from Org A Flow │ │Event from Org B │ │ │ │ │ │ │ │ │ │ │ │ │ │ ╭─────────────────╮ │ │ ╭─────────────────────╮ ╭──────────────────────────╮ ┌──────────────────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ "Organization A │ │ │ │ 📋 Event from Org A │ │ 📋 Event from Org B │ ┌┄┄┄┄┄┤ OrgHierarchy │ │ │ │ │ │ (Parent │ │ │ │ │ │ │ ┆ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┆ │ │ │ │ │ │ ╰────────┬────────╯ │ │ ╰──────────┬──────────╯ ╰─────────────┬────────────╯ ┆ └──────────────────────────┘ │ │ │ │ │ │ │ │ │ ┆ │ │ │ │ │ │ │ │ │ ┆ │ │ │ │ │ │ │ ├┄┄┄┄┄┄┄┄┄┄┄┄┄┐┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄└┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤ │ │ │ │ │ │ │ ┆ │ │ │ │ │ │ ▼ │ │ ▼ │ │ │ │ │ │ ╭─────────────────╮ │ │ ┌─────────────────────┐ │ ╭──────────────────────────╮ │ ╭──────────────────────────╮ ╭─────────────────────────╮ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ "Organization B │ │ │ │ FlowA │ └─►│ "AidboxSubscriptionTopic ├─✅─Forward►│ "AidboxTopicDestination ├❌─Filtered─out─►│ Kafka │ │ │ │ │ │ (Child of Org A │ │ │ │ │ │ (related to Org A │ │ │ (related to Org B │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ╰─────────────────╯ │ │ └──────────┬──────────┘ ╰──────────────────────────╯ │ ╰──────────────────────────╯ ╰─────────────────────────╯ │ │ │ │ │ │ ┆ │ │ │ │ └─────────────────────┘ └────────────┆─────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────┘ │ │ ┆ │ │ │ ┆ │ │ │ ┆ │ │ │ ┌─────────────────┐ ┆ │ ╭──────────────────────────╮ ╭─────────────────────────╮ │ ╭───────╮ │ │ │ ┆ │ │ │ │ │ │ │ │ │ │ │ ┆ │ │ │ │ │ │ │ │ │ │ FlowB │◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘ └────►│ "AidboxSubscriptionTopic ├───✅─Forward───►│ "AidboxTopicDestination ├─✅─Forward►│ Kafka │ │ │ │ │ (related to Org A │ │ (related to Org B │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────────┘ ╰──────────────────────────╯ ╰─────────────────────────╯ │ ╰───────╯ │ │ │ └─────────────────┘ ``` **Filtering behavior:** * ✅ **Event from Org A**: Processed by the topic (same organization) but filtered out at the aidbox topic destination level * ✅ **Event from Org B**: Processed by the topic (child organization) and forwarded to destination at the aidbox topic destination level * ❌ **Event from unrelated organization**: Would be filtered out at the subscription topic level #### Example 2: Filtering at the destination level only Consider an organization structure which two organizations `Organization A` and `Organization B`. The diagram below shows how events flow through the subscription system when filtering is applied at the destination level only: ``` ┌───────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ ┌──────────────────────┐ │ Organization Hierarchy │ │ Event from Org A Flow │ │Event from Org B Flow │ │ │ │ │ │ │ │ │ │ │ │ │ │ ╭────────────────╮ ╭────────────────╮ │ │ ╭─────────────────────╮ ╭─────────────────────────╮ ┌─────────────────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ Organization A │ │ Organization B │ │ │ │ 📋 Event from Org A │ │ 📋 Event from Org B │ ┌┄┄┄┄┄┤ OrgHierarchy │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┆ │ │ │ │ │ │ ╰────────────────╯ ╰────────────────╯ │ │ ╰──────────┬──────────╯ ╰────────────┬────────────╯ ┆ └─────────────────────────┘ │ │ │ │ │ │ │ │ ┆ │ │ │ └───────────────────────────────────────────┘ │ │ │ ┆ │ │ │ ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄└┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤ │ │ │ ┆ │ │ │ │ │ │ ▼ │ │ │ │ │ │ ┌────────────────┐ │ │ ╭─────────────────────────╮ │ ╭─────────────────────────╮ ╭─────────────────────────╮ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ FlowA │ │ └───────────────►│ AidboxSubscriptionTopic ├─✅─Forward►│ "AidboxTopicDestination ├─✅─Forward►│ Kafka │ │ │ │ │ │ │ │ │ │ │ (related to Org A │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └────────┬───────┘ │ ╰─────────────────────────╯ │ ╰─────────────────────────╯ ╰─────────────────────────╯ │ │ │ ┆ │ │ │ │ │ ┆ └─────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────┘ │ │ ┆ │ │ │ ┆ │ │ │ ▼ │ │ │ ┌────────────────┐ │ ╭─────────────────────────╮ ╭─────────────────────────╮ │ ╭───────╮ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ FlowB │ └────►│ AidboxSubscriptionTopic ├─✅─Forward►│ "AidboxTopicDestination ├❌─Filtered─out─►│ Kafka │ │ │ │ │ │ │ (related to Org A │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └────────────────┘ ╰─────────────────────────╯ ╰─────────────────────────╯ │ ╰───────╯ │ │ │ └──────────────────────┘ ``` **Filtering behavior:** * ✅ **Event from Org A**: Processed by the topic (no filtering) and forwarded to aidbox topic destination * ✅ **Event from Org B**: Processed by the topic (no filtering) but filtered out at the aidbox topic destination level * ❌ **Event from unrelated organization**: Would be filtered out at the aidbox topic destination level ## Notification Shape Notification is a [FHIR Bundle](https://build.fhir.org/bundle.html) resource with `history` type, containing relevant resources in its entries. The first entry is a `AidboxSubscriptionStatus` resource, which describes the payload.\ The other entries depend on `AidboxTopicDestination.content` element. This element has the binding to the FHIR [subscription-payload-content](https://hl7.org/fhir/valueset-subscription-payload-content.html) value set: `full-resource` | `id-only` | `empty` {% tabs %} {% tab title="full-resource" %} ```json { "resourceType":"Bundle", "type":"history", "timestamp":"2024-10-03T10:07:55Z", "entry":[ { "resource":{ "resourceType":"AidboxSubscriptionStatus", "status":"active", "type":"event-notification", "notificationEvent":[ { "eventNumber":1, "focus":{ "reference":"QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b" } } ], "topic":"http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic", "topic-destination":{ "reference":"AidboxTopicDestination/kafka-destination" } } }, { "resource":{ "id":"458e771c-0ff1-4858-ac07-93b7a10c8e3b", "item":[ { "text":"Leishmania sp 14kD IgG Ser Ql IB", "answer":[ { "valueString":"123" } ], "linkId":"128852" }, { "text":"Leishmania sp 16kD IgG Ser Ql IB", "answer":[ { "valueString":"432" } ], "linkId":"128851" } ], "meta":{ "lastUpdated":"2024-10-03T10:07:55.843374Z", "versionId":"1970", "extension":[ { "url":"ex:createdAt", "valueInstant":"2024-10-03T10:07:42.342731Z" } ] }, "author":{ "identifier":{ "type":{ "coding":[ { "code":"UID", "system":"urn:system:aidbox", "display":"User ID" } ] }, "value":"admin", "system":"http://localhost:8765" } }, "status":"completed", "authored":"2024-10-03T10:07:55.664Z", "resourceType":"QuestionnaireResponse", "questionnaire":"http://loinc.org/q/100109-8" }, "fullUrl": "http://aidbox-server/fhir/QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b", "request":{ "method":"POST", "url":"/fhir/QuestionnaireResponse" } } ] } ``` {% endtab %} {% tab title="id-only" %} ```json { "resourceType":"Bundle", "type":"history", "timestamp":"2024-10-03T10:07:55Z", "entry":[ { "resource":{ "resourceType":"AidboxSubscriptionStatus", "status":"active", "type":"event-notification", "notificationEvent":[ { "eventNumber":1, "focus":{ "reference":"QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b" } } ], "topic":"http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic", "topic-destination":{ "reference":"AidboxTopicDestination/kafka-destination" } } }, { "fullUrl": "http://aidbox-server/fhir/QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b", "request":{ "method":"POST", "url":"/fhir/QuestionnaireResponse" } } ] } ``` {% endtab %} {% tab title="empty" %} ```json { "resourceType":"Bundle", "type":"history", "timestamp":"2024-10-03T10:07:55Z", "entry":[ { "resource":{ "resourceType":"AidboxSubscriptionStatus", "status":"active", "type":"event-notification", "notificationEvent":[ { "eventNumber":1, "focus":{ "reference":"QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b" } } ], "topic":"http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic", "topic-destination":{ "reference":"AidboxTopicDestination/kafka-destination" } } } ] } ``` {% endtab %} {% endtabs %} ### Entry extensions When `includeEntryAction` or `includeVersionId` is enabled on the `AidboxTopicDestination`, each resource `Bundle.entry` (except the `AidboxSubscriptionStatus` entry) will include an `extension` array with the corresponding values: ```json { "resource": { ... }, "fullUrl": "...", "request": { ... }, "extension": [ { "url": "http://health-samurai.io/fhir/core/StructureDefinition/bundle-entryActionCode", "valueCode": "create" }, { "url": "http://health-samurai.io/fhir/core/StructureDefinition/bundle-entryVersionId", "valueId": "1970" } ] } ``` Only the extensions corresponding to the enabled flags are included. The extensions appear on entries for both `full-resource` and `id-only` content modes. In `empty` mode there are no resource entries, so extensions are not included. ### Focus reference with version id When `includeVersionIdInFocusReference` is enabled, the `focus.reference` in each `notificationEvent` includes the version history path: ```json { "notificationEvent": [ { "eventNumber": 1, "focus": { "reference": "Patient/123/_history/5" } } ] } ``` Without this flag, the reference would be `Patient/123`. ### Delivery logging When `enableLogging` is set to `true` on an `AidboxTopicDestination`, Aidbox logs the `AidboxSubscriptionStatus` resource after each delivery attempt. On successful delivery, the status is logged as-is. On failure, the status includes an `error` array. The `logLevel` element controls the log level used for these messages. For example, setting `logLevel` to `"error"` emits logs at the error level, while the default `"info"` emits at the info level. The configured level must be equal to or higher than the system-wide log level setting — otherwise the messages will be filtered out and will not appear in the logs. ```json { "resourceType": "AidboxSubscriptionStatus", "id": "auto-generated-uuid", "status": "active", "type": "event-notification", "topic": "http://example.org/FHIR/R5/SubscriptionTopic/patient-topic", "topic-destination": { "reference": "AidboxTopicDestination/my-destination" }, "error": ["Connection refused: localhost:1"] } ``` The logs are emitted with the event key `topic-destination/status`.