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: ???' \
  --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: ???' \
  --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: ???' \
  --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: ???' \
  --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.