Descripció general dels webhooks

Què són els webhooks?

Els webhooks permeten a vitalera enviar notificacions HTTP POST en temps real a la vostra aplicació quan es produeixen esdeveniments a la plataforma. En lloc de consultar l'API per canvis, els webhooks envien dades al vostre punt d'accés tan aviat com es produeixen els esdeveniments.

Com funciona

1. Configureu un URL de webhook a la configuració de la vostra organització vitalera
2. Seleccioneu els tipus d'esdeveniment que voleu rebre
3. Establiu un secret per a la verificació de signatura
4. vitalera envia peticions HTTP POST al vostre URL quan es produeixen esdeveniments coincidents

Tipus d'esdeveniment

Tipus d'esdeveniment	Activador
observation.created	Es registra una nova observació per a un pacient
alarm.triggered	Una regla d'alarma s'activa per una observació
alarm.resolved	Una alarma prèviament activada es resol
consent.granted	Un pacient atorga consentiment de compartició de dades
consent.revoked	Un pacient revoca el consentiment
questionnaire_response.submitted	Un pacient envia una resposta a un qüestionari
care_plan.activated	Un pla de cures s'activa
care_plan.completed	Un pla de cures arriba a la seva data de fi o es completa

Càrrega útil del webhook

Totes les càrregues útils de webhooks segueixen una estructura consistent:

{
  "event_type": "observation.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": 42,
  "data": {
    "id": 810,
    "resourceType": "Observation",
    "observation_definition": {
      "observation_name": "heart_rate",
      "observation_method": "device"
    },
    "category": "physiological_data",
    "value": "72",
    "value_type": "int",
    "value_unit": "bpm",
    "issued": "2024-01-15T10:30:00Z",
    "effective_datetime": "2024-01-15T10:30:00Z",
    "source_id": 1
  }
}

Exemple d'alarma activada

{
  "event_type": "alarm.triggered",
  "timestamp": "2024-01-15T10:31:00Z",
  "organization_id": 42,
  "data": {
    "alarm_id": 55,
    "alarm_name": "High Heart Rate",
    "severity": "high",
    "patient_id": 123,
    "triggering_observation": {
      "observation_name": "heart_rate",
      "value": "145",
      "value_unit": "bpm"
    }
  }
}

Verificació de signatura

Totes les trucades de webhook inclouen una capçalera x-webhook-signature que conté una signatura HMAC-SHA256 del cos de la petició, calculada amb el vostre secret de webhook.

Per verificar un webhook:

1. Extraieu el valor de la capçalera x-webhook-signature
2. Calculeu l'HMAC-SHA256 del cos brut de la petició utilitzant el vostre secret de webhook
3. Compareu la signatura calculada amb el valor de la capçalera (utilitzeu comparació de temps constant)

Exemple Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Exemple Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Bones pràctiques de seguretat

• Utilitzeu sempre punts d'accés HTTPS
• Establiu un secret únic per configuració de webhook
• Verifiqueu la signatura en cada petició entrant abans de processar-la
• Responeu amb 200 OK ràpidament i processeu la càrrega útil de manera asíncrona
• Emmagatzemeu el secret del webhook de manera segura (p. ex., variable d'entorn, gestor de secrets)

Política de reintents

Si el vostre punt d'accés retorna una resposta diferent de 2xx o s'esgota el temps, vitalera reintenta amb reintent exponencial:

Intent	Retard
1r reintent	~1 minut
2n reintent	~5 minuts
3r reintent	~30 minuts
4t reintent	~2 hores

Després d'exhaurir tots els reintents, l'esdeveniment es marca com a fallat. Podeu revisar els lliuraments fallats a la configuració de la vostra organització.

Necessiteu ajuda?

Contacteu amb support@vitalera.io per configurar webhooks per a la vostra organització.