> For the complete documentation index, see [llms.txt](https://help.santesuite.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.santesuite.org/developers/service-apis/hl7-fhir/santedb-fhir-implementation/publish-subscribe.md).

# FHIR Subscriptions

SanteDB supports subscribing to resource events via the creation of `Subscription` resource instances. 

{% hint style="info" %}
Currently the SanteDB iCDR PubSub layer does not use persistence queues for retry/resubmit. This feature is currently under construction, as of version 2.1.x PubSub requests are realtime push notifications and the use of an external reliable delivery method is recommended.
{% endhint %}

## Creating Subscriptions

The underlying implementation of the FHIR Subscription mechanism is the SanteDB PubSub broker, when a `Subscription` resource is created the SanteDB iCDR service interacts with the PubSub broker to:

* Create a new channel definition with the appropriate endpoint and authentication information, 
* Creates a new subscription definition with the appropriate filter criteria,
* Activates the subscription if `active` is set to true.

For example, consider this subscription request

```javascript
{
  "resourceType": "Subscription",
  "id": "my_subscription",
  "status": "active",
  "contact": [
    {
      "system": "phone",
      "value": "180086626362"
    }
  ],
  "end": "2025-01-01T00:00:00Z",
  "reason": "Monitor Creation of Female Patients",
  "criteria": "Patient?gender=female",
  "channel": {
    "type": "rest-hook",
    "endpoint": "http://localhost:8989/fhir/Patient",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer secret-token-abc-123"
    ]
  }
}
```

This subscription definition would:

* Create a new channel definition pointing at [http://localhost:8989\&#x20](https://help.santesuite.org/developers/service-apis/hl7-fhir/santedb-fhir-implementation/http:/localhost:8989\&#x20);
  * Content/Type would be added (`application/fhir+json`) to the channel definition
  * Authorization header (`bearer secret-token-abc-123`) added to the channel definition
  * The channel dispatcher would be mapped from `rest-hook` to the `FhirRestHookDispatcher`
* Create a new subscription definition :
  * FHIR resource type `Patient` would be mapped to target `SanteDB.Core.Model.Roles.Patient`
  * Filter criteria `gender=female` would be mapped to HDSI filter `genderConcept.referenceTerm.mnemonic=female`
  * Subscription would be activated
  * Subscription would have a `notAfter` time set of `2025-01-01`

### Supported Dispatchers

The SanteDB iCDR supports the following dispatchers on the channel:

| Type           | Channel Scheme     | Dispatcher                              |
| -------------- | ------------------ | --------------------------------------- |
| rest-hook      | fhir-rest-http\:// | `FhirPubSubRestHookDispatcher`          |
| message        | fhir-msg-http\://  | `FhirPubSubMessageDispatcher`           |
| sms            | sms\://            | Default handler for SMS messages        |
| email          | mailto://          | Default handler for e-mail messages     |
| llp (extended) | llp\://            | Notify using HL7v2 LL (extended option) |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.santesuite.org/developers/service-apis/hl7-fhir/santedb-fhir-implementation/publish-subscribe.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.