Webhooks-overzicht

Wat zijn webhooks?

Webhooks stellen vitalera in staat om realtime HTTP POST-meldingen naar uw applicatie te sturen wanneer gebeurtenissen op het platform plaatsvinden. In plaats van de API te pollen voor wijzigingen, pushen webhooks gegevens naar uw endpoint zodra gebeurtenissen plaatsvinden.

Hoe het werkt

1. Configureer een webhook-URL in uw vitalera-organisatie-instellingen
2. Selecteer de gebeurtenistypen die u wilt ontvangen
3. Stel een geheim in voor handtekeningverificatie
4. vitalera stuurt HTTP POST-verzoeken naar uw URL wanneer overeenkomende gebeurtenissen plaatsvinden

Gebeurtenistypen

Gebeurtenistype	Trigger
observation.created	Een nieuwe observatie wordt vastgelegd voor een patient
alarm.triggered	Een alarmregel wordt getriggerd door een observatie
alarm.resolved	Een eerder getriggerd alarm is opgelost
consent.granted	Een patient geeft toestemming voor gegevensdeling
consent.revoked	Een patient trekt toestemming in
questionnaire_response.submitted	Een patient dient een vragenlijstantwoord in
care_plan.activated	Een zorgplan wordt geactiveerd
care_plan.completed	Een zorgplan bereikt zijn einddatum of wordt voltooid

Webhook-payload

Alle webhook-payloads volgen een consistente structuur:

{
  "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
  }
}

Voorbeeld: getriggerd alarm

{
  "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"
    }
  }
}

Handtekeningverificatie

Alle webhook-oproepen bevatten een x-webhook-signature-header met een HMAC-SHA256-handtekening van de verzoekbody, berekend met uw webhook-geheim.

Een webhook verifieren:

1. Extraheer de x-webhook-signature-headerwaarde
2. Bereken HMAC-SHA256 van de ruwe verzoekbody met uw webhook-geheim
3. Vergelijk de berekende handtekening met de headerwaarde (gebruik constante-tijdvergelijking)

Python-voorbeeld

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)

Node.js-voorbeeld

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));
}

Best practices voor beveiliging

• Gebruik altijd HTTPS-eindpunten
• Stel een uniek geheim in per webhook-configuratie
• Verifieer de handtekening bij elk inkomend verzoek voordat u het verwerkt
• Reageer snel met 200 OK en verwerk de payload asynchroon
• Sla het webhook-geheim veilig op (bijv. omgevingsvariabele, secrets manager)

Herhalingsbeleid

Als uw eindpunt een niet-2xx-antwoord retourneert of een time-out heeft, probeert vitalera het opnieuw met exponential backoff:

Poging	Vertraging
1e poging	~1 minuut
2e poging	~5 minuten
3e poging	~30 minuten
4e poging	~2 uur

Nadat alle pogingen zijn uitgeput, wordt de gebeurtenis als mislukt gemarkeerd. U kunt mislukte leveringen bekijken in uw organisatie-instellingen.

Hulp nodig?

Neem contact op met support@vitalera.io om webhooks voor uw organisatie te configureren.