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.type=rest-hook
O campo channel.endpoint é obrigatório e é a URL que receberá as notificações
O criteria precisa começar com um tipo de recurso FHIR válido (ex.: Patient, Encounter?status=finished)
Para criação o campo status sempre deve ser requested
Antes de ativar a assinatura, a Nilo envia um handshake para o channel.endpoint. Enquanto ele não for respondido com sucesso, nenhuma notificação é enviada
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 vigente com o mesmo criteria, exceto se a existente estiver com status=error. O criteria é comparado por igualdade exata, incluindo os query params
Se informado, o campo contact aceita apenas itens com system=email e endereços de e-mail válidos. Esses contatos recebem o alerta de desativação

Alterar a URL ou os critérios de uma assinatura

Não existe atualização "no lugar": para trocar o channel.endpoint ou o criteria, é preciso desabilitar a assinatura atual (status=off) e criar uma nova. As duas operações podem ir na mesma request via Bundle.

Ciclo de vida e status da Subscription

Status	Significado
`requested`	Assinatura criada, aguardando o handshake de validação. Ainda não recebe notificações.
`active`	Handshake respondido com sucesso. A assinatura está recebendo notificações.
`error`	Desativada automaticamente após falhas seguidas na entrega. Não recebe notificações, mas é reativada automaticamente assim que o endpoint voltar a responder.
`off`	Desabilitada manualmente (envio de `status=off`). Só volta a existir criando uma nova assinatura.

O fluxo normal é: requested → (handshake OK) → active. Se o handshake falhar, a assinatura vai direto para error.

Na resposta da criação, a Subscription retorna com um meta.tag cujo code é o identificador interno do webhook na Nilo:

{
"meta": {
  "tag": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/landing-zone-api--f-h-i-r-webhook",
      "code": "1234"
    }
  ]
}
}

Esse tag também pode ser usado para buscar a assinatura depois:

curl -X GET 'https://landing-zone-api.nilo.services/fhir/resources/Subscription?_tag=https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/landing-zone-api--f-h-i-r-webhook|1234' \
-H 'X-Api-Key: <sua-api-key>'

Handshake de validação

Ao criar uma Subscription, a Nilo envia um POST de validação para o channel.endpoint antes de começar a notificar. O corpo é um Bundle do tipo history contendo um SubscriptionStatus com type=handshake:

{
"resourceType": "Bundle",
"type": "history",
"entry": [
  {
    "fullUrl": "urn:uuid:...",
    "resource": {
      "resourceType": "SubscriptionStatus",
      "status": "requested",
      "type": "handshake",
      "eventsSinceSubscriptionStart": "0",
      "subscription": {
        "type": "Subscription",
        "identifier": {
          "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/landing-zone-api--f-h-i-r-webhook",
          "value": "1234"
        }
      }
    }
  }
]
}

O handshake usa os mesmos cabeçalhos das notificações (incluindo X-Hub-Signature e a autenticação configurada).

Se o seu endpoint responder 2xx, a assinatura passa para status=active e começa a receber notificações.
Se responder qualquer status de erro, a assinatura vai para status=error e o motivo fica registrado no campo error da Subscription.

cuidado

O handshake é assíncrono: o POST de criação da Subscription responde com status=requested e a ativação acontece logo em seguida. Consulte a Subscription para confirmar a ativação.

Cabeçalhos enviados nas notificações

Cabeçalho	Descrição
`Content-Type`	Sempre `application/fhir+json`.
`X-Hub-Signature`	Assinatura HMAC-SHA256 do corpo da requisição. Veja Validando a assinatura.
`Authorization`	Enviado quando informado em `channel.header` ou quando o OAuth2 está habilitado.
Demais cabeçalhos de `channel.header`	Repassados sem alteração em todas as notificações e no handshake.

Validando a assinatura (X-Hub-Signature)

Toda notificação (e o handshake) leva o cabeçalho X-Hub-Signature, no formato:

X-Hub-Signature: sha256=<hmac_sha256_hex>

O valor é o HMAC-SHA256 do corpo bruto da requisição, usando o secret da assinatura como chave, em hexadecimal.

Definindo o secret

O secret é informado como um item de channel.header com a chave secret:

{
"channel": {
  "type": "rest-hook",
  "endpoint": "https://endpoint.cliente.com/api/webhook",
  "header": [
    "secret:meu-segredo-super-secreto",
    "Authorization:<token>"
  ]
}
}

Se o secret não for informado, a Nilo gera um automaticamente. Em ambos os casos o valor pode ser consultado no channel.header da Subscription retornada na criação.

nota

Os cabeçalhos informados em channel.header são repassados nas notificações, inclusive o secret. Prefira validar a requisição pelo X-Hub-Signature, e não pelo cabeçalho secret.

Exemplo de validação

import hashlib
import hmac

def is_valid(raw_body: bytes, signature_header: str, secret: str) -> bool:
  digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
  return hmac.compare_digest(f"sha256={digest}", signature_header)

const crypto = require('crypto');

function isValid(rawBody, signatureHeader, secret) {
const digest = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(
  Buffer.from(`sha256=${digest}`),
  Buffer.from(signatureHeader),
);
}

cuidado

Calcule o HMAC sobre o corpo exatamente como recebido. Serializar novamente o JSON (mudando espaços ou ordem de chaves) invalida a assinatura.

Entrega, retentativas e desativação automática

A Nilo espera uma resposta 2xx. O tempo limite é de 5 segundos para conectar e 15 segundos para responder.
Falhas de rede, timeouts, respostas 5xx e 429 são reprocessadas automaticamente por algumas tentativas.
Respostas 4xx (exceto 429) são tratadas como falha permanente: aquele evento não é reenviado.
A partir da terceira tentativa de entrega sem sucesso, a assinatura é desativada (status=error), o motivo é gravado no campo error da Subscription e um alerta é enviado por e-mail.

Enquanto a assinatura está em error, nenhuma notificação é entregue — e os eventos ocorridos nesse período não são reenviados depois. Para não perder dados, reconcilie o período usando o GET do recurso correspondente.

Reativação automática

A assinatura em error não precisa ser recriada. No próximo evento daquele tipo de recurso, a Nilo reenvia o handshake para o seu endpoint; se ele responder 2xx, a assinatura volta para active e o evento é entregue normalmente.

Alerta por e-mail

Se a Subscription tiver o campo contact preenchido com e-mails, esses endereços recebem um alerta quando a assinatura é desativada, contendo o criteria, o endpoint, o status HTTP, a mensagem de erro e o link para o recurso FHIR que não pôde ser entregue.

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"
},
"contact": [
 {
   "system": "email",
   "value": "integracoes@cliente.com"
 }
],
"criteria": "Patient",
"reason": "Receive patient upserts",
"resourceType": "Subscription",
"status": "requested"
}
'
  

Notificações de exclusão

Quando um recurso é excluído, a notificação envia o recurso com um meta.tag de código DELETE:

{
"resourceType": "Patient",
"id": "ac5cc304-ff64-4f6c-a3fc-49a8fb26269e",
"meta": {
  "tag": [
    {"code": "DELETE"}
  ]
}
}

Como o recurso já não existe mais na base no momento da exclusão, os filtros do criteria são avaliados sobre a cópia enviada no evento: apenas os parâmetros active, status e o modificador :missing são aplicados. Filtros mais complexos não são avaliados nesse caso, e a notificação de exclusão é enviada mesmo assim.

Bundles

Eventos de Bundle só geram notificação quando o Bundle é do tipo document.

Autenticação no endpoint do webhook

Existem duas formas de autenticar as notificações que a Nilo envia para o seu endpoint:

Cabeçalhos estáticos — informados em channel.header na criação da Subscription (por exemplo "Authorization:<token>"). São enviados sem alteração em todas as notificações.
OAuth2 (client credentials) — configurado pela equipe de suporte da Nilo. Antes de cada notificação a Nilo obtém um access token no seu provedor OAuth2 e o envia no cabeçalho Authorization: Bearer <access_token>.

OAuth2 via configuração pelo suporte

O OAuth2 não é configurado pela API: ele é habilitado pela equipe de suporte da Nilo, por cliente (care provider), e passa a valer para todas as Subscription daquele cliente. Para solicitar, abra um pedido para o suporte da Nilo informando os dados abaixo.

Campo	Obrigatório	Descrição
`token_url`	Sim	URL do endpoint de token do seu provedor OAuth2.
`client_id`	Sim	Identificador do client.
`client_secret`	Sim	Secret do client.
`grant_type`	Não	Padrão `client_credentials`.
`scopes`	Não	Lista de scopes. Enviados no campo `scope`, separados por espaço.
`audience`	Não	Enviado no campo `audience` da requisição de token.
`client_authentication`	Não	Como as credenciais são enviadas: `basic_auth` (padrão, via cabeçalho HTTP Basic) ou `body_data` (no corpo da requisição).
`headers`	Não	Cabeçalhos adicionais na requisição de token. Se incluir `Content-Type: application/json`, o corpo é enviado como JSON em vez de `application/x-www-form-urlencoded`.

Exemplo dos dados a enviar para o suporte:

{
"token_url": "https://auth.cliente.com/oauth2/token",
"client_id": "nilo-webhook",
"client_secret": "<secret>",
"grant_type": "client_credentials",
"scopes": ["webhook:write"],
"audience": "https://api.cliente.com",
"client_authentication": "basic_auth"
}

Como funciona a entrega das notificações com OAuth2 habilitado:

A Nilo faz um POST no token_url com o grant client_credentials e usa o access_token retornado no cabeçalho Authorization: Bearer <access_token> da notificação.
O token é reaproveitado até pouco antes de expirar (com base no expires_in da resposta) e renovado automaticamente.
Ao rotacionar qualquer credencial ou parâmetro da configuração, um novo token é obtido imediatamente, sem esperar o token anterior expirar.
O cabeçalho Authorization passa a ser controlado pela Nilo. Se houver um Authorization em channel.header, ele será substituído pelo token OAuth2.
A configuração também vale para o handshake enviado na criação da Subscription, então o endpoint de token precisa estar acessível antes de criar a assinatura.

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

Agendamento sem link de vídeo

Payload de exemplo enviado de appointment sem link de vídeo
{
  "resourceType": "Appointment",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "identifier": [
    {
      "use": "usual",
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--scheduling-v2",
      "value": "789"
    },
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/agendamento/",
      "value": "AG-98765"
    }
  ],
  "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",
  "appointmentType": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/appointment-type",
        "code": "ONLINE",
        "display": "Atendimento Online"
      }
    ]
  },
  "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"
    }
  ]
}

Agendamento com link de vídeo

Payload de exemplo enviado de appointment com link de vídeo
{
  "resourceType": "Appointment",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "identifier": [
    {
      "use": "usual",
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--scheduling-v2",
      "value": "789"
    },
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/agendamento/",
      "value": "AG-98765"
    }
  ],
  "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",
  "appointmentType": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/appointment-type",
        "code": "ONLINE",
        "display": "Atendimento Online"
      }
    ]
  },
  "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",
        "identifier": [
          {
            "use": "usual",
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--scheduling-v2",
            "value": "789"
          },
          {
            "use": "usual",
            "system": "https://www.acmesaude.com.br/integracao/agendamento/",
            "value": "AG-98765"
          }
        ],
        "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",
        "appointmentType": {
          "coding": [
            {
              "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/appointment-type",
              "code": "ONLINE",
              "display": "Atendimento Online"
            }
          ]
        },
        "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",
        "identifier": [
          {
            "use": "usual",
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--scheduling-v2",
            "value": "789"
          },
          {
            "use": "usual",
            "system": "https://www.acmesaude.com.br/integracao/agendamento/",
            "value": "AG-98765"
          }
        ],
        "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",
        "appointmentType": {
          "coding": [
            {
              "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/appointment-type",
              "code": "ONLINE",
              "display": "Atendimento Online"
            }
          ]
        },
        "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",
        "identifier": [
          {
            "use": "usual",
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--scheduling-v2",
            "value": "789"
          },
          {
            "use": "usual",
            "system": "https://www.acmesaude.com.br/integracao/agendamento/",
            "value": "AG-98765"
          }
        ],
        "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",
        "appointmentType": {
          "coding": [
            {
              "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/appointment-type",
              "code": "ONLINE",
              "display": "Atendimento Online"
            }
          ]
        },
        "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"
      }
    }
  ]
}

Ciclo de vida e status da Subscription​

Handshake de validação​

Cabeçalhos enviados nas notificações​

Validando a assinatura (X-Hub-Signature)​

Definindo o secret​

Exemplo de validação​

Entrega, retentativas e desativação automática​

Reativação automática​

Alerta por e-mail​

Notificações de exclusão​

Autenticação no endpoint do webhook​

OAuth2 via configuração pelo suporte​

Criação de Subscription para Patient

Criação de Subscription para Encounter incluindo recursos relacionados

Desabilitar de Subscription

Uso de Bundle para desabilitar e habilitar webhook na mesma request​

Webhook de Agendamentos​

Criação de Subscription para Appointment​

Payload de exemplo enviado para o endpoint do webhook​

Agendamento sem link de vídeo​

Agendamento com link de vídeo​

Recebendo agendamentos incluindo recursos relacionados (_include)​

Incluindo Paciente relacionado​

Criação de Subscription​

Payload de exemplo enviado para o endpoint do webhook​

Incluindo Profissional relacionado​

Payload de exemplo enviado para o endpoint do webhook​

Incluindo Profissional e paciente relacionado​

Payload de exemplo enviado para o endpoint do webhook​

Ciclo de vida e status da Subscription

Handshake de validação

Cabeçalhos enviados nas notificações

Validando a assinatura (X-Hub-Signature)

Definindo o secret

Exemplo de validação

Entrega, retentativas e desativação automática

Reativação automática

Alerta por e-mail

Notificações de exclusão

Autenticação no endpoint do webhook

OAuth2 via configuração pelo suporte

Uso de Bundle para desabilitar e habilitar webhook na mesma request

Webhook de Agendamentos

Criação de Subscription para Appointment

Payload de exemplo enviado para o endpoint do webhook

Agendamento sem link de vídeo

Agendamento com link de vídeo

Recebendo agendamentos incluindo recursos relacionados (_include)

Incluindo Paciente relacionado

Criação de Subscription

Payload de exemplo enviado para o endpoint do webhook

Incluindo Profissional relacionado

Payload de exemplo enviado para o endpoint do webhook

Incluindo Profissional e paciente relacionado

Payload de exemplo enviado para o endpoint do webhook