Webhooks Uebersicht

Was sind Webhooks?

Webhooks ermoeglichen es vitalera, Echtzeit-HTTP-POST-Benachrichtigungen an Ihre Anwendung zu senden, wenn Ereignisse auf der Plattform eintreten. Anstatt die API nach Aenderungen abzufragen, senden Webhooks Daten an Ihren Endpunkt, sobald Ereignisse eintreten.

Funktionsweise

1. Konfigurieren Sie eine Webhook-URL in Ihren vitalera-Organisationseinstellungen
2. Waehlen Sie die Ereignistypen, die Sie empfangen moechten
3. Legen Sie ein Geheimnis fest fuer die Signaturverifizierung
4. vitalera sendet HTTP-POST-Anfragen an Ihre URL, wenn passende Ereignisse eintreten

Ereignistypen

Ereignistyp	Ausloeser
observation.created	Eine neue Beobachtung wird fuer einen Patienten aufgezeichnet
alarm.triggered	Eine Alarmregel wird durch eine Beobachtung ausgeloest
alarm.resolved	Ein zuvor ausgeloester Alarm wird aufgeloest
consent.granted	Ein Patient erteilt Einwilligung zur Datenfreigabe
consent.revoked	Ein Patient widerruft die Einwilligung
questionnaire_response.submitted	Ein Patient reicht eine Fragebogenantwort ein
care_plan.activated	Ein Pflegeplan wird aktiviert
care_plan.completed	Ein Pflegeplan erreicht sein Enddatum oder wird abgeschlossen

Webhook-Payload

Alle Webhook-Payloads folgen einer einheitlichen Struktur:

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

Beispiel: Ausgeloester 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"
    }
  }
}

Signaturverifizierung

Alle Webhook-Aufrufe enthalten einen x-webhook-signature-Header mit einer HMAC-SHA256-Signatur des Anfragebodys, die mit Ihrem Webhook-Geheimnis berechnet wird.

So verifizieren Sie einen Webhook:

1. Extrahieren Sie den x-webhook-signature-Headerwert
2. Berechnen Sie HMAC-SHA256 des rohen Anfragebodys mit Ihrem Webhook-Geheimnis
3. Vergleichen Sie die berechnete Signatur mit dem Headerwert (verwenden Sie Konstantzeitvergleich)

Python-Beispiel

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-Beispiel

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 fuer Sicherheit

• Verwenden Sie immer HTTPS-Endpunkte
• Legen Sie ein eindeutiges Geheimnis pro Webhook-Konfiguration fest
• Verifizieren Sie die Signatur bei jeder eingehenden Anfrage vor der Verarbeitung
• Antworten Sie schnell mit 200 OK und verarbeiten Sie den Payload asynchron
• Speichern Sie das Webhook-Geheimnis sicher (z. B. Umgebungsvariable, Secrets-Manager)

Wiederholungsrichtlinie

Wenn Ihr Endpunkt eine Nicht-2xx-Antwort zurueckgibt oder das Zeitlimit ueberschreitet, wiederholt vitalera mit exponentiellem Backoff:

Versuch	Verzoegerung
1. Versuch	~1 Minute
2. Versuch	~5 Minuten
3. Versuch	~30 Minuten
4. Versuch	~2 Stunden

Nachdem alle Wiederholungen erschoepft sind, wird das Ereignis als fehlgeschlagen markiert. Sie koennen fehlgeschlagene Zustellungen in Ihren Organisationseinstellungen ueberpruefen.

Brauchen Sie Hilfe?

Kontaktieren Sie support@vitalera.io, um Webhooks fuer Ihre Organisation zu konfigurieren.