Skip to main content

Subscriptions

Subscriptions are event-driven notifications, like webhooks, and are commonly used for integrations and automations. Medplum supports subscribing to changes on FHIR resources. There is a description FHIR Subscriptions on HL7.org that describes the functionality in detail.

Limit of 1,000 persisted active Subscriptions per project

When a resource changes, the server loads at most 1,000 persisted active Subscriptions in the project. Cached WebSocket listeners are added separately; this is not a combined limit on all listeners.

Planning Automations​

Before using Subscriptions for intake, messaging, work queues, or migration side effects, decide:

  • Scale and triggers: Keep persisted subscriptions within the project limit and scope their criteria to the required resources and events. Use create/update and transition criteria to avoid processing unrelated edits.
  • Tenant scope and execution identity: A Subscription with meta.accounts only matches resources sharing at least one account, even when its search criteria match. Verify inherited account assignments as described in Publish and Subscribe. A Bot normally uses its own membership; select Run as User deliberately. Do not assume the subscription author's policy defines the Bot's permissions.
  • Idempotency: Use stable identifiers and conditional writes for generated resources. Track external deliveries separately so replaying an event does not duplicate a message, order, or payment.
  • Failure recovery: Assign an owner for detecting and recovering failed work. Application-level Bot handler failures are not automatically retried by subscription-max-attempts; errors thrown during setup or invocation may still retry. External HTTP endpoints have a configurable retry policy. Test recovery for the endpoint type you use.

Additional Documentation

  • Use the subscription tag to quickly find all documentation related to Subscriptions
  • Resending Webhooks describes the $resend operation for manually triggering webhooks
  • Subscription Extensions describes advanced subscription features that allow more fine-grained control and security
  • WebSocket Subscriptions describes WebSocket subscriptions and usage of them via the React useSubscription hook
  • Server-Scoped Subscriptions describes the self-hosted feature that lets a super admin create a single Subscription that fires across every project on the server