Zum Inhalt springen
Resilience Platform Resilience Platform

Developer

API-Versionierung & Webhooks

Dokumentation des API-Versionierungsmodells, Webhook-Events, Retry-Logik und Integrationsmuster.

API-Versionierungsmodell

Die Resilience Platform verwendet ein kompatibles Major-Versionierungsschema. Änderungen werden in CHANGELOG-Einträgen dokumentiert.

v1 (aktuell)

Stabile API-Version für Produktion. Alle aktuellen Endpoints unter /api/v1/*.

Support bis mindestens Q4 2027

v2 (geplant)

Nächste Major-Version mit verbesserter GraphQL-Unterstützung und erweiterten Webhook-Payloads.

Release: Q2 2027

Deprecation Policy

Minimale Übergangsfrist von 12 Monaten nach Ankündigung. Breaking Changes werden im Changelog und per E-Mail an API-Key-Inhaber kommuniziert.

API-Versionen & Endpoints

Version Endpoint Status Changelog
v1/api/v1/*Stablev1.3.2 (2026-05-28): Neue Webhook-Test-Endpoints
v1/api/v1/webhooksStablev1.3.0 (2026-04-15): Webhook-Registrierung & Test
v1/api/v1/measuresStablev1.2.0 (2026-03-01): Erweiterte Filterparameter
v1/api/v1/evidenceStablev1.1.0 (2026-01-15): Erstes Release
v2/api/v2/*PreviewIn Entwicklung – GraphQL-Playground, Webhook-Signaturen

Webhook-Events

Folgende Events können über Webhooks abonniert werden. Payloads werden als JSON an die registrierte Callback-URL gesendet.

Event Beschreibung Sample Payload
measure.updated Eine DORA-Maßnahme wurde aktualisiert (Status, Reifegrad, Verantwortlicher) 
{
  "event": "measure.updated",
  "id": "DORA-ICT-007",
  "title": "IKT-Risikoanalyse",
  "status": "implemented",
  "maturity": "Managed",
  "updated_by": "a.martens@example.com",
  "timestamp": "2026-06-14T10:30:00Z"
}
evidence.created Ein neues Evidence-Item wurde hochgeladen oder erstellt 
{
  "event": "evidence.created",
  "id": "ev-20260614-001",
  "filename": "ikt-risikoanalyse-v3.pdf",
  "category": "risk_assessment",
  "measure_id": "DORA-ICT-007",
  "uploaded_by": "a.martens@example.com",
  "timestamp": "2026-06-14T11:00:00Z"
}
incident.reported Ein IKT-Vorfall wurde gemeldet oder klassifiziert 
{
  "event": "incident.reported",
  "id": "INC-2026-047",
  "severity": "high",
  "title": "Ausfall Zahlungsverkehrssystem",
  "status": "reported",
  "reported_by": "a.martens@example.com",
  "timestamp": "2026-06-14T12:15:00Z"
}
finding.closed Eine Prüfungsfeststellung wurde abgeschlossen 
{
  "event": "finding.closed",
  "id": "FND-2026-112",
  "title": "Fehlende Zugriffsprotokollierung",
  "closed_by": "a.martens@example.com",
  "resolution": "SIEM-Logging implementiert und getestet",
  "timestamp": "2026-06-14T14:00:00Z"
}
test.completed Ein Testprogramm oder Testfall wurde abgeschlossen 
{
  "event": "test.completed",
  "id": "TP-2026-003",
  "title": "TLPT-Simulation Zahlungsverkehr",
  "result": "passed",
  "test_type": "tlpt",
  "completed_by": "a.martens@example.com",
  "timestamp": "2026-06-14T15:30:00Z"
}
register.exported Ein Informationsregister-Export wurde generiert 
{
  "event": "register.exported",
  "id": "REG-EXP-20260614-001",
  "format": "csv",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "exported_by": "a.martens@example.com",
  "timestamp": "2026-06-14T16:00:00Z"
}

Rate Limiting

API-Endpoints

60/min

Pro IP-Adresse

Webhook-Out

300/h

Pro Ziel-URL

Export-Endpoints

30/min

Pro IP-Adresse

Bei Überschreitung wird der HTTP-Status 429 Too Many Requests mit einem Retry-After-Header zurückgegeben.

Webhook-Retry-Logik

Fehlgeschlagene Webhook-Zustellungen werden automatisch wiederholt. Die Strategie folgt einem exponentiellen Backoff mit maximaler Obergrenze.

Exponential Backoff

1. Versuch: sofort
2. Versuch: nach 10s
3. Versuch: nach 30s
4. Versuch: nach 2min
5. Versuch: nach 10min

Max Retries

5 Zustellversuche pro Event. Nach dem fünften Fehlschlag wird das Event in die Dead Letter Queue verschoben.

Dead Letter Queue

Nicht zustellbare Events werden 7 Tage in der DLQ aufbewahrt und können manuell erneut ausgelöst werden. Nach 7 Tagen erfolgt automatische Bereinigung.

Beispiel-Webhook-Payload (vollständig)

Jeder Webhook-Callback enthält die folgenden Felder im JSON-Body:

{
  "schema_version": "v1",
  "event": "measure.updated",
  "id": "DORA-ICT-007",
  "title": "IKT-Risikoanalyse",
  "status": "implemented",
  "maturity": "Managed",
  "updated_by": "a.martens@example.com",
  "timestamp": "2026-06-14T10:30:00Z",
  "links": {
    "self": "https://resilience.amartens.com/api/v1/measures/DORA-ICT-007",
    "webhook": "https://resilience.amartens.com/webhooks/wh-abc123"
  },
  "headers": {
    "X-Webhook-ID": "wh-abc123",
    "X-Webhook-Event": "measure.updated",
    "X-Webhook-Signature": "sha256=abc123def456...",
    "X-Webhook-Delivery": "del-20260614-001"
  }
}

Die Signatur wird mit HMAC-SHA256 aus dem Webhook-Secret und dem Payload-Body gebildet. Empfänger müssen die Signatur validieren, um die Authentizität sicherzustellen.

ISO 27001 Verbindung

ISO/IEC 27001:2022 steuert API-Sicherheit, Webhook-Integrität und Datenschutz bei der Übertragung.

  • A.5.1 Informationssicherheitsrichtlinien
  • A.5.36 Compliance mit Sicherheitsanforderungen
  • A.5.37 Dokumentierte Betriebsverfahren

ISO/IEC 27001:2022 dient als Kontrollanker und Management-System-Referenz. Die Verbindung zu ISO 27001 unterstützt integrierte Resilienz- und Sicherheitsprogramme.

Reifegrad

  1. 1 Initial

    Ad-hoc-Ansätze, keine formalen Prozesse

  2. 2 Defined

    Formale Prozesse definiert, aber nicht durchgängig umgesetzt

  3. 3 Implemented

    Prozesse vollständig umgesetzt und dokumentiert

  4. 4 Monitored

    Prozesse werden überwacht und gemessen

  5. 5 Optimized

    Kontinuierliche Verbesserung und Anpassung