Zum Hauptinhalt springen

API Webhooks, Testplans und API-Token-Info

· 3 Minuten Lesezeit
Jan Wittkamp
Jan Wittkamp
CEO @ Memida GmbH

In der Welt der APIs ist Stillstand keine Option. Mit diesem Update erweitern wir die Funktionalität der Memida-API erheblich: Die Einführung von Webhooks ermöglicht Echtzeit-Benachrichtigungen, während die neuen Testplan-Endpunkte eine präzisere Verwaltung und Integration von Prüfplänen erlauben. Zusätzlich bietet die erweiterte API-Token-Info mehr Kontext und Sicherheit für Ihre Anwendungen.

Abb.:1 Memida API

Neue Webhook-API​

Neue Endpunkte​

  • GET /api/v1/webhooks/subscriptions
  • POST /api/v1/webhooks/subscriptions
  • PUT /api/v1/webhooks/subscriptions/{id}
  • DELETE /api/v1/webhooks/subscriptions/{id}
  • POST /api/v1/webhooks/subscriptions/{id}/test

Wichtige Regeln​

  • Pro Subscription ist genau ein event_type erlaubt.
  • target_url und event_type sind nach Erstellung immutable.
  • Für URL- oder Event-Wechsel muss eine neue Subscription angelegt werden.
  • description steht als freies Feld für FE-/Benutzerkontext zur Verfügung.
  • Die Eventtypen sind direkt in der OpenAPI-Doku dokumentiert.

Aktuelle Event-Typen​

  • apparatus.created
  • apparatus.updated
  • inspection.created
  • inspection.updated

Outgoing Webhooks​

Outgoing-Header:

  • X-Memida-Id
  • X-Memida-Event
  • X-Memida-Timestamp
  • X-Memida-Signature (v1=<hmac>)

Signatur-Bildung:

HMAC-SHA256(secret, timestamp + "." + rawJsonBody)

Ein Beispiel zur Validierung der Signatur findet sich in der Api Dokumentation unter Webhooks.

Payload enthält:

  • event_id, event_type, organization_id (UUID), company_id (UUID)
  • data.resource.{type,id,api_path}
  • optional data.changed
  • optional data.changed_fields (wenn Delta fehlt oder unvollständig ist)

Delivery-Semantik:

  • at-least-once
  • Empfänger sollten über event_id deduplizieren

Retries/Deaktivierung:

  • Retry-Backoff ist aktiv.
  • Eine Subscription wird nach 20 aufeinanderfolgenden Fehlschlägen deaktiviert.

Security:

  • Nur HTTPS-Ziele
  • SSRF-Schutz (keine privaten/lokalen Ziele, keine URL-Credentials)
  • Kein Redirect-Follow
  • Timeout: connect 3s, total 10s

Benutzeransicht​

Abb.:2 Webhook Benutzer Ansicht

Webhooks können auch von einem admin im Benutzerbereich angelegt (1), eingesehen und veraltet werden. Zum einfachen Testen der Funktionalität können Test-Anfragen generiert (3) und Webhooks wenn sie nicht mehr benötigt werden deaktiviert (2) werden. Das Secret wird automatisch generiert und dem Benutzer nur 1x angezeigt, kopieren Sie sich das Secret und überprüfen Sie es, sobald ein Webhook-Event ausgelöst wird.

API Token Info​

GET /api/v1/info liefert jetzt zusätzlich:

  • organization_id (UUID)
  • company_id (UUID)

Damit können Clients eingehende Webhooks eindeutig dem richtigen Organisation- und Token-Kontext zuordnen.

Testplans API​

Neue Endpunkte​

  • GET /api/v1/testplans (Pagination, Filter apparatus_id, Sort/Page/Limit)
  • POST /api/v1/testplans (JSON oder multipart mit files)
  • GET /api/v1/testplans/{testplan_id}
  • PUT /api/v1/testplans/{testplan_id} (inkl. optionaler Datei-Uploads)

Neue Informationen zur Bedienung der Funktion finden Sie in unserem Handbuch.