For a full list of available versions, see the Directory of published versions

4.1.8. 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.

4.1.8.1. Scope

4.1.8.2.

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 will mark the subscription in error, and no further notifications are sent until the issue is resolved.

4.1.8.3. Interaction Sequence Diagram

4.1.8.4.

4.1.8.5. Specification

Handshake Request

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

`POST [Subscription Endpoint]`, 

Handshake Response

The Subscriver returns a 200 OK HTTP status code.

4.1.8.6. Example of Handshake Interaction

Example Handshake Request

HTTP Method:

POST

Headers:

Content-Type: application/fhir+json

Address:

[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" }
   }
 ]