Interaction: Handshake

The FHIR Handshake Interaction is the initial verification and trust-establishment process that occurs between a Subscription Server and a Subscriber system when a subscription is first created or activated. It ensures that the Subscriber’s notification endpoint is valid, reachable, and capable of handling notifications before the Subscription becomes active.

Scope

When a Subscription resource is created or updated to an active state, the Subscription Server initiates a handshake interaction by sending a SubscriptionStatus notification of type handshake to the Subscriber’s notification endpoint defined in the Subscription.

This handshake acts as a “ping” message that tests connectivity and confirms that the Subscriber endpoint:

Exists and is reachable over the network.

Accepts requests from the Subscription Server (authentication/authorization succeeds).

Correctly processes a SubscriptionStatus message.

If the Subscriber successfully responds (e.g., HTTP 200/202/204), the Subscription Server considers the handshake successful and transitions the subscription to an active operational state.

If the Subscriber fails to respond or returns an error, the server may mark the subscription as error, and no further notifications are sent until the issue is resolved.

Interaction Sequence Diagram

Specification

Handshake Request

The Subscription Server sends a handshake request to Subscriber's endpoint.

`POST [base]/Subscription Endpoint`, 

Handshake Response

The Subscriver returns a 200 OK HTTP status code.

Example of Handshake Interaction

Example Handshake Request

HTTP Method:

POST

Headers:

Content-Type: application/fhir+json

Address:

[base]/Subscription Endpoint

HTTP Body contains a Subscription Status Notifiction Bundle Resource

{
 "resourceType": "Bundle",
 "id": "r4b-notification-handshake",
 "meta": {
   "profile": [
     "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription-notification"
   ]
 },
 "type": "history",
 "timestamp": "2020-05-29T11:44:13.1882432-05:00",
 "entry": [
   {
     "fullUrl": "urn:uuid:9d98f2be-4067-4b90-b0ec-6d3308d75c8e",
     "resource": {
       "resourceType": "SubscriptionStatus",
       "id": "9d98f2be-4067-4b90-b0ec-6d3308d75c8e",
       "status": "requested",
       "type": "handshake",
       "eventsSinceSubscriptionStart": "0",
       "subscription": { "reference": "https://example.org/fhir/Subscription/admission" },
       "topic": "http://hl7.org/SubscriptionTopic/admission"
     },
     "request": {
       "method": "GET",
       "url": "https://example.org/fhir/Subscription/admission/$status"
     },
     "response": { "status": "200" }
   }
 ]
 

Expected Behaviour