Pular para o conteúdo principal

Webhook

Para inscrever um webhook é usado o Subscription do FHIR. Depois que uma assinatura é criada, qualquer recurso novo ou atualizado que atenda aos critérios especificados, resulta no envio de uma notificação para o webhook fornecido. Esses critérios são os mesmos utilizados no search por meio da API REST. É importante citar que os critérios de pesquisa são aplicados ao valor atual do recurso.

Nos POST que envia as notificações irá um cabeçalho Content-Type com o valor do application/fhir+json e seu servidor deve está preparado para aceitá-lo.

Algumas regras são utilizadas para criar ou atualizar uma Subscription. São elas:

  • No momento suportamos apenas channel do tipo rest-hook
  • Campo url do channel é obrigatório
  • Uma requisição de teste é enviada para a url do channel e caso retorne um status de erro não serão enviadas notificações para o webhook.
  • Para criação o campo status sempre deve ser requested
  • Para desabilitar deve enviar o status off e a Subscription deve estar com status=active ou status=requested
  • Não é possível ter mais de uma Subscription com status=active e mesmo criteria

Criação de Subscription para Patient

Exemplo de requisição CURL

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Subscription \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '
{
"channel": {
 "endpoint": "https://endpoint.cliente.com/api/webhook",
 "header": [
   "Authorization:<token>"
 ],
 "payload": "application/fhir+json",
 "type": "rest-hook"
},
"criteria": "Patient",
"reason": "Receive patient upserts",
"resourceType": "Subscription",
"status": "requested"
}
'

Pare esse exemplo, sempre que um Patient for criado ou atualizado será enviado uma cópia para o webhook.


Criação de Subscription para Encounter incluindo recursos relacionados

Para incluir relacionamentos deve usar os query_params _include (referencia direta (1)) e _revinclude(referencia reversa (N))

Exemplo de requisição CURL

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Subscription \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '
{
"channel": {
 "endpoint": "https://endpoint.cliente.com/api/webhook",
 "header": [
   "Authorization:<token>"
 ],
 "payload": "application/fhir+json",
 "type": "rest-hook"
},
"criteria": "Encounter?_revinclude=ServiceRequest:encounter&_include=Encounter:subject",
"reason": "Receive encounter + relationships",
"resourceType": "Subscription",
"status": "requested"
}
'

Para esse exemplo será enviado um Bundle para o webhook com o Encounter , Patient (subject) e ServiceRequest(s) relacionados ao Encounter criado/alterado.


{
"entry": [
 {
   "resource": {
     "class": {...},
     "id": "1fad0fb7-3a2e-4e18-98a9-3151ff3145d7",
     "identifier": [...],
     "meta": {...},
     "participant": [...],
     "resourceType": "Encounter",
     "status": "in-progress",
     "subject": {...},
   },
   "search": {
     "mode": "match"
   }
 },
 {
   "resource": {
     "active": true,
     "communication": [...],
     "extension": [...],
     "gender": "male",
     "id": "ac5cc304-ff64-4f6c-a3fc-49a8fb26269ec",
     "identifier": [...],
     "managingOrganization": {...},
     "maritalStatus": {...},
     "meta": {...},
     "name": [...],
     "resourceType": "Patient"
   },
   "search": {
     "mode": "include"
   }
 },
 {
   "resource": {
     "authoredOn": "2023-11-22",
     "encounter": {
       "identifier": {...},
       "reference": "Encounter/1fad0fb7-3a2e-4e18-98a9-3151ff3145d7",
       "type": "Encounter"
     },
     "id": "381336ff-8802-495f-aa50-7417323cbc24",
     "identifier": [...],
     "intent": "order",
     "locationReference": [...],
     "meta": {...},
     "reasonCode": [...],
     "requester": {...},
     "resourceType": "ServiceRequest",
     "status": "active",
     "subject": {
       "identifier": {...},
       "reference": "Patient/ad75d697-23c9-468e-8137-ffd718d4f6ac",
       "type": "Patient"
     }
   },
   "search": {
     "mode": "include"
   }
 }
],
"resourceType": "Bundle",
"total": 1,
"type": "searchset"
}

Desabilitar de Subscription

Supondo que existe uma subscription para notificar criação e atualização de pacientes somente se estiverem ativos (observe a criteria abaixo), então o payload seria:

Exemplo de requisição CURL

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Subscription \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '
{
"channel": {
 "endpoint": "https://endpoint.cliente.com/api/webhook",
 "header": [
   "Authorization:<token>"
 ],
 "payload": "application/fhir+json",
 "type": "rest-hook"
},
"criteria": "Patient?active=true",
"reason": "Receive encounter",
"resourceType": "Subscription",
"status": "off" // status para desabilitar
}
'

Uso de Bundle para desabilitar e habilitar webhook na mesma request

Para usar o Bundle com propósito de desabilitar e habilitar webhooks, os primeiros itens do entry precisam ser aqueles que serão desabilitados.

Exemplo de requisição CURL

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Bundle \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
 {
   "fullUrl": "urn:uuid:247255c8-4052-470f-a500-1e79ae1b9963",
   "request": {
     "url": "Subscription",
     "method": "POST"
   },
   "resource": {
     "resourceType": "Subscription",
     "status": "off",
     "criteria": "Encounter",
     "channel": {
       "endpoint": "https://endpoint.cliente.com/api/webhook",
       "header": [
         "Authorization:<token>"
       ],
       "payload": "application/fhir+json",
       "type": "rest-hook"
     },
     "reason": "Remove Receive ServiceRequest"
   }
 },
 {
   "fullUrl": "urn:uuid:247255c8-4052-470f-a500-1e79ae1b9964",
   "request": {
     "url": "Subscription",
     "method": "POST"
   },
   "resource": {
     "resourceType": "Subscription",
     "status": "requested",
     "criteria": "Encounter?_revinclude=ServiceRequest:encounter",
     "channel": {
       "endpoint": "https://endpoint.cliente.com/api/webhook",
       "header": [
         "Authorization:<token>"
       ],
       "payload": "application/fhir+json",
       "type": "rest-hook"
     },
     "reason": "Add Receive ServiceRequest"
   }
 }
]
}
'

No exemplo acima o primeiro entry desabilitando a Subscription de Encounter e o segundo cria uma nova também para Encounter, mas adicionando as referências de ServiceRequest.

Webhook de Agendamentos​

A Nilo pode enviar notificações via webhook para informar sobre eventos relacionados a agendamentos.

Criação de Subscription para Appointment​

Criação de Subscription para Appointment

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Subscription \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "channel": {
    "endpoint": "https://endpoint.cliente.com/api/webhook",
    "header": [
      "Authorization:<token>"
    ],
    "payload": "application/fhir+json",
    "type": "rest-hook"
  },
  "criteria": "Appointment",
  "reason": "Receive appointment events",
  "resourceType": "Subscription",
  "status": "requested"
}'

Payload de exemplo enviado para o endpoint do webhook​

Payload de exemplo enviado de appointment sem link de vídeo
{
  "resourceType": "Appointment",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "booked",
  "description": "Consulta de retorno",
  "start": "2024-09-28T20:32:56.528762+00:00",
  "end": "2024-09-28T21:02:56.528762+00:00",
  "created": "2024-09-27T20:30:56.528762+00:00",
  "comment": "Comentários sobre o agendamento",
  "participant": [
    {
      "actor": {
        "type": "Patient",
        "identifier": {
          "use": "usual",
          "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--patient-v2",
          "value": "123"
        },
        "reference": "Patient/d77bd7b0-144d-4789-9e81-062a375addb8"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "type": "Practitioner",
        "identifier": {
          "use": "usual",
          "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--professional",
          "value": "456"
        },
        "reference": "Practitioner/1e8f3c9e-6f4b-4c3b-9d2e-1c2b3a4d5e6f"
      },
      "status": "accepted"
    }
  ]
}
Payload de exemplo enviado de appointment com link de vídeo
{
  "resourceType": "Appointment",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "booked",
  "description": "Consulta de retorno",
  "start": "2024-09-28T20:32:56.528762+00:00",
  "end": "2024-09-28T21:02:56.528762+00:00",
  "created": "2024-09-27T20:30:56.528762+00:00",
  "comment": "Comentários sobre o agendamento",
  "contained": [
    {
      "address": "https://nilovideo.app/f/51236",
      "connectionType": {
        "code": "https"
      },
      "payloadType": [
        {
          "text": "video"
        }
      ],
      "resourceType": "Endpoint",
      "status": "active"
    }
  ],
  "participant": [
    {
      "actor": {
        "type": "Patient",
        "identifier": {
          "use": "usual",
          "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--patient-v2",
          "value": "123"
        },
        "reference": "Patient/d77bd7b0-144d-4789-9e81-062a375addb8"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "type": "Practitioner",
        "identifier": {
          "use": "usual",
          "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--professional",
          "value": "456"
        },
        "reference": "Practitioner/1e8f3c9e-6f4b-4c3b-9d2e-1c2b3a4d5e6f"
      },
      "status": "accepted"
    }
  ]
}

Recebendo agendamentos incluindo recursos relacionados (_include)​

Quando adicionado o _include no criteria, o payload enviado para o endpoint do webhook será um Bundle e pode conter múltiplos recursos no entry.

Incluindo Paciente relacionado​

Criação de Subscription​
Criação de Subscription para Appointment incluindo Paciente relacionado

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Subscription \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "channel": {
    "endpoint": "https://endpoint.cliente.com/api/webhook",
    "header": [
      "Authorization:<token>"
    ],
    "payload": "application/fhir+json",
    "type": "rest-hook"
  },
  "criteria": "Appointment?_include=Appointment:actor:Patient",
  "reason": "Receive appointment + patient",
  "resourceType": "Subscription",
  "status": "requested"
}'

Payload de exemplo enviado para o endpoint do webhook​

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Appointment",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "status": "booked",
        "description": "Consulta de retorno",
        "start": "2024-09-28T20:32:56.528762+00:00",
        "end": "2024-09-28T21:02:56.528762+00:00",
        "created": "2024-09-27T20:30:56.528762+00:00",
        "comment": "Comentários sobre o agendamento",
        "contained": [
          {
            "address": "https://nilovideo.app/f/51236",
            "connectionType": {
              "code": "https"
            },
            "payloadType": [
              {
                "text": "video"
              }
            ],
            "resourceType": "Endpoint",
            "status": "active"
          }
        ],
        "participant": [
          {
            "actor": {
              "type": "Patient",
              "identifier": {
                "use": "usual",
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--patient-v2",
                "value": "123"
              },
              "reference": "Patient/d77bd7b0-144d-4789-9e81-062a375addb8"
            },
            "status": "accepted"
          },
          {
            "actor": {
              "type": "Practitioner",
              "identifier": {
                "use": "usual",
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--professional",
                "value": "456"
              },
              "reference": "Practitioner/1e8f3c9e-6f4b-4c3b-9d2e-1c2b3a4d5e6f"
            },
            "status": "accepted"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "resource": {
        "resourceType": "Patient",
        "identifier": [
          {
            "use": "usual",
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709"
          },
          {
            "use": "usual",
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--patient-v2",
            "value": "123"
          }
        ],
        "name": [
          {
            "use": "official",
            "family": "Silveira",
            "given": [
              "João"
            ]
          }
        ]
      },
      "search": {
        "mode": "include"
      }
    }
  ]
}

Incluindo Profissional relacionado​

Criação de Subscription para Appointment incluindo Profissional relacionado

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Subscription \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "channel": {
    "endpoint": "https://endpoint.cliente.com/api/webhook",
    "header": [
      "Authorization:<token>"
    ],
    "payload": "application/fhir+json",
    "type": "rest-hook"
  },
  "criteria": "Appointment?_include=Appointment:actor:Practitioner",
  "reason": "Receive appointment + relationships",
  "resourceType": "Subscription",
  "status": "requested"
}'

Payload de exemplo enviado para o endpoint do webhook​

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Appointment",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "status": "booked",
        "description": "Consulta de retorno",
        "start": "2024-09-28T20:32:56.528762+00:00",
        "end": "2024-09-28T21:02:56.528762+00:00",
        "created": "2024-09-27T20:30:56.528762+00:00",
        "comment": "Comentários sobre o agendamento",
        "contained": [
          {
            "address": "https://nilovideo.app/f/51236",
            "connectionType": {
              "code": "https"
            },
            "payloadType": [
              {
                "text": "video"
              }
            ],
            "resourceType": "Endpoint",
            "status": "active"
          }
        ],
        "participant": [
          {
            "actor": {
              "type": "Patient",
              "identifier": {
                "use": "usual",
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--patient-v2",
                "value": "123"
              },
              "reference": "Patient/d77bd7b0-144d-4789-9e81-062a375addb8"
            },
            "status": "accepted"
          },
          {
            "actor": {
              "type": "Practitioner",
              "identifier": {
                "use": "usual",
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--professional",
                "value": "456"
              },
              "reference": "Practitioner/1e8f3c9e-6f4b-4c3b-9d2e-1c2b3a4d5e6f"
            },
            "status": "accepted"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "resource": {
        "resourceType": "Practitioner",
        "identifier": [
          {
            "use": "usual",
            "system": "https://www.acmesaude.com.br/integracao/profissional/",
            "value": "5032932"
          },
          {
            "use": "usual",
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--professional",
            "value": "456"
          }
        ],
        "name": [
          {
            "text": "Jon Doe",
            "use": "official"
          }
        ]
      },
      "search": {
        "mode": "include"
      }
    }
  ]
}

Incluindo Profissional e paciente relacionado​

Criação de Subscription para Appointment incluindo Paciente e Profissional relacionados

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Subscription \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "channel": {
    "endpoint": "https://endpoint.cliente.com/api/webhook",
    "header": [
      "Authorization:<token>"
    ],
    "payload": "application/fhir+json",
    "type": "rest-hook"
  },
  "criteria": "Appointment?_include=Appointment:actor:Practitioner&_include=Appointment:actor:Patient",
  "reason": "Receive appointment + relationships",
  "resourceType": "Subscription",
  "status": "requested"
}'

Payload de exemplo enviado para o endpoint do webhook​

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Appointment",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "status": "booked",
        "description": "Consulta de retorno",
        "start": "2024-09-28T20:32:56.528762+00:00",
        "end": "2024-09-28T21:02:56.528762+00:00",
        "created": "2024-09-27T20:30:56.528762+00:00",
        "comment": "Comentários sobre o agendamento",
        "contained": [
          {
            "address": "https://nilovideo.app/f/51236",
            "connectionType": {
              "code": "https"
            },
            "payloadType": [
              {
                "text": "video"
              }
            ],
            "resourceType": "Endpoint",
            "status": "active"
          }
        ],
        "participant": [
          {
            "actor": {
              "type": "Patient",
              "identifier": {
                "use": "usual",
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--patient-v2",
                "value": "123"
              },
              "reference": "Patient/d77bd7b0-144d-4789-9e81-062a375addb8"
            },
            "status": "accepted"
          },
          {
            "actor": {
              "type": "Practitioner",
              "identifier": {
                "use": "usual",
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--professional",
                "value": "456"
              },
              "reference": "Practitioner/1e8f3c9e-6f4b-4c3b-9d2e-1c2b3a4d5e6f"
            },
            "status": "accepted"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "resource": {
        "resourceType": "Practitioner",
        "identifier": [
          {
            "use": "usual",
            "system": "https://www.acmesaude.com.br/integracao/profissional/",
            "value": "5032932"
          },
          {
            "use": "usual",
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--professional",
            "value": "456"
          }
        ],
        "name": [
          {
            "text": "Jon Doe",
            "use": "official"
          }
        ]
      },
      "search": {
        "mode": "include"
      }
    },
    {
      "resource": {
        "resourceType": "Patient",
        "identifier": [
          {
            "use": "usual",
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709"
          },
          {
            "use": "usual",
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--patient-v2",
            "value": "123"
          }
        ],
        "name": [
          {
            "use": "official",
            "family": "Silveira",
            "given": [
              "João"
            ]
          }
        ]
      },
      "search": {
        "mode": "include"
      }
    }
  ]
}