Fhir Webhooks

generated: '2026-11-05'
method: searched
source: https://hl7.org/fhir/subscriptions.html
docs: https://hl7.org/fhir/subscriptions.html
description: 'FHIR Subscriptions (R5, subscriptions.html) are the specification''s push mechanism: a client creates
  a Subscription resource naming a SubscriptionTopic, a channel and a payload type, and the server sends notifications
  (Bundles of type subscription-notification) to the client''s endpoint. The rest-hook channel is the webhook form:
  "when using the rest-hook channel type the endpoint is the HTTP server listening for notifications". Topics (the
  event vocabulary) are defined by each server through SubscriptionTopic resources, not by the core specification,
  so no event catalog is listed here.'
mechanism: FHIR Subscription resource + SubscriptionTopic; notification Bundles
channels:
- type: rest-hook
  description: HTTP POST of the notification Bundle to a client-provided endpoint; "when using a rest-hook the client
    must pre-configure an HTTP endpoint which the server validates"
- type: websocket
  description: '"when using a websocket the client simply connects to the server"'
- type: email
  description: notification delivered by email (channel type defined by the specification)
- type: message
  description: '"When combining Messaging and Subscriptions, complete notifications are wrapped into Messaging Bundles."'
payloads:
- empty
- id-only
- full-resource
delivery:
  handshake: '"If applicable, the server MAY send a handshake to the endpoint. If the Server sends a handshake,
    the endpoint SHALL respond appropriately, or the Server MAY deactivate the subscription."'
  heartbeat: Servers MAY modify the request to be suitable (e.g., changing heartbeat timeouts, etc.); clients SHALL
    check the returned resource for the accepted version.
  retries: not specified by the core specification
  signature: not specified; "Using content types of empty or id-only can mitigate this risk, as resources must be
    retrieved from a trusted location prior to use."
events:
- event: handshake
  description: Notification sent by the server to verify a newly created subscription endpoint; the endpoint SHALL
    respond or the server MAY deactivate the subscription.
  declared_in: https://hl7.org/fhir/subscriptions.html
- event: heartbeat
  description: Periodic notification the server MAY send to show the subscription is alive; the interval (heartbeat
    timeout) is negotiated on the Subscription resource.
  declared_in: https://hl7.org/fhir/subscriptions.html