Webhooks verwalten

Webhooks ermöglichen es Auris, deine externen Systeme zu benachrichtigen, wenn Authentifizierungsereignisse auftreten — wie Benutzererstellung, Anmeldung, Passwortänderungen, Rollenzuweisungen und mehr. Anstatt die Auris-API auf Änderungen zu pollen, erhält dein Server Echtzeit-HTTP-POST-Benachrichtigungen mit Ereignisdetails.

Zugriff auf die Webhook-Verwaltung unter Konsole → Einstellungen → Webhooks.

Webhook-Übersicht

Die Webhooks-Seite zeigt alle konfigurierten Webhook-Endpunkte für deinen Tenant:

Einen Webhook erstellen

Webhook-Geheimnis

Jedem Webhook wird bei der Erstellung ein Signierungsgeheimnis zugewiesen. Dieses Geheimnis wird verwendet, um HMAC-SHA256-Signaturen für jede Übermittlung zu generieren, sodass dein Server verifizieren kann, dass eingehende Webhooks tatsächlich von Auris stammen.

Das Geheimnis anzeigen

Das Signierungsgeheimnis wird einmalig sofort nach der Webhook-Erstellung in einem Bestätigungsdialog angezeigt. Es wird mit whsec_ vorangestellt zur leichten Identifizierung:

whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Kopiere das Geheimnis und speichere es sicher in den Umgebungsvariablen deiner Anwendung. Das Geheimnis wird nach dem Schließen des Dialogs nicht mehr angezeigt.

Webhook-Signaturen verifizieren

Jede Webhook-Übermittlung enthält zwei Header zur Signaturverifizierung:

Verifizierungsschritte auf deinem Server:

1. Den X-Webhook-Timestamp-Header lesen
2. Den Zeitstempel auf einen akzeptablen Rahmen prüfen (z. B. 5 Minuten), um Replay-Angriffe zu verhindern
3. HMAC-SHA256(timestamp + "." + requestBody, webhookSecret) berechnen
4. Die berechnete Signatur mit dem X-Webhook-Signature-Header vergleichen

Beispiel-Verifizierung in Node.js:

import { createHmac, timingSafeEqual } from 'crypto'
 
function verifyWebhook(
  body: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Zeitstempel-Aktualität prüfen (5-Minuten-Fenster)
  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return false // Zu alt oder zu weit in der Zukunft
  }
 
  // Erwartete Signatur berechnen
  const payload = `${timestamp}.${body}`
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
 
  // Zeitkonstanter Vergleich zur Verhinderung von Timing-Angriffen
  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Webhooks testen

Bevor du in der Produktion bereitstellst, verifiziere, dass dein Endpunkt Webhook-Payloads korrekt empfängt und verarbeitet.

Test-Ereignis senden

Klicke auf der Webhook-Detailseite auf die Schaltfläche Test. Auris sendet ein Test-Ereignis an die konfigurierte URL mit einem Beispiel-Payload:

{
  "event": "webhook.test",
  "timestamp": "2025-02-10T08:15:00Z",
  "data": {
    "message": "Dies ist eine Test-Webhook-Übermittlung von Auris."
  }
}

Die Test-Übermittlung erscheint im Übermittlungs-Protokoll, sodass du den Antwort-Statuscode verifizieren und eventuelle Fehlermeldungen sehen kannst.

Webhook-Test-Werkzeuge verwenden

Für die Entwicklung kannst du einen Webhook-Testdienst wie webhook.site  oder ngrok  verwenden, um Webhook-Payloads zu empfangen und zu untersuchen:

1. Erstelle eine temporäre URL mit deinem Test-Werkzeug
2. Setze diese URL als Webhook-Endpunkt in der Konsole
3. Löse Ereignisse aus (z. B. einen Test-Benutzer erstellen)
4. Untersuche den empfangenen Payload im Test-Werkzeug
5. Aktualisiere die Webhook-URL auf deinen Produktionsendpunkt, wenn bereit

Übermittlungen anzeigen

Jeder Webhook-Endpunkt hat ein Übermittlungsprotokoll, das jedes an ihn gesendete Ereignis zeigt.

Greife auf das Übermittlungsprotokoll zu, indem du einen Webhook in der Liste anklickst, um die Detailseite zu öffnen, und dann zum Abschnitt Übermittlungen scrollst.

Übermittlungsstatus

Klicke auf eine Übermittlungszeile, um vollständige Details anzuzeigen:

• Anfrage-Payload: Der an deinen Endpunkt gesendete JSON-Body
• Antwort-Body: Die von deinem Endpunkt zurückgegebene Antwort (erste 1 KB)
• Antwort-Header: Zurückgegebene HTTP-Header
• Fehlermeldung: Falls die Übermittlung fehlgeschlagen ist, der spezifische Fehler

Fehlgeschlagene Übermittlungen wiederholen

Auris wiederholt fehlgeschlagene Übermittlungen (5xx, Timeout, Netzwerkfehler) automatisch mit exponentiellem Backoff:

Nach 3 fehlgeschlagenen Versuchen wird die Übermittlung als fehlgeschlagen markiert und es werden keine weiteren automatischen Wiederholungen durchgeführt.

Manuelle Wiederholung

So wiederholst du eine fehlgeschlagene Übermittlung manuell:

1. Öffne die Webhook-Detailseite
2. Finde die fehlgeschlagene Übermittlung im Protokoll
3. Klicke auf die Schaltfläche Wiederholen in dieser Übermittlungszeile

Die manuelle Wiederholung sendet exakt denselben Payload an die aktuelle Webhook-URL. Wenn du die URL seit der ursprünglichen Übermittlung geändert hast, geht die Wiederholung an die neue URL.

Geheimnisse rotieren

Wenn du vermutest, dass ein Webhook-Geheimnis kompromittiert wurde, oder wenn du Geheimnisse als Teil einer Sicherheitsrichtlinie rotieren musst, kannst du ein neues Geheimnis generieren:

Wichtig: Die Rotation ist sofortig. Sobald du rotierst, ist das alte Geheimnis ungültig und alle nachfolgenden Übermittlungen werden mit dem neuen Geheimnis signiert. Wenn dein Endpunkt noch mit dem alten Geheimnis konfiguriert ist, werden Übermittlungen abgelehnt, bis du es aktualisierst. Plane für ein kurzes Fenster fehlgeschlagener Übermittlungen während der Rotation.

So minimierst du Unterbrechungen:

1. Aktualisiere deinen Endpunkt-Code, um Signaturen von beiden alten oder neuen Geheimnissen zu akzeptieren
2. Rotiere das Geheimnis in der Konsole
3. Nachdem du bestätigt hast, dass Übermittlungen mit dem neuen Geheimnis erfolgreich sind, entferne das alte Geheimnis aus deinem Endpunkt-Code

Webhooks aktivieren und deaktivieren

Jeder Webhook hat einen Aktiv-Umschalter auf seiner Detailseite. Wenn deaktiviert:

• Keine Ereignisse werden an den Endpunkt übermittelt
• Die Webhook-Konfiguration bleibt erhalten (URL, Ereignisse, Geheimnis)
• Im deaktivierten Zustand erscheinen keine Übermittlungen im Protokoll
• Das Wiederaktivieren nimmt Übermittlungen für neue Ereignisse wieder auf (Ereignisse, die während der Deaktivierung aufgetreten sind, werden nicht erneut abgespielt)

Verwende dies, um Übermittlungen während der Endpunkt-Wartung vorübergehend zu pausieren, ohne die Webhook-Konfiguration zu verlieren.

Ereigniskategorien-Übersicht

Auris unterstützt über 50 Webhook-Ereignistypen, organisiert in folgenden Kategorien:

Jeder Ereignis-Payload folgt einer konsistenten Struktur:

{
  "event": "user.created",
  "timestamp": "2025-02-10T08:15:00Z",
  "tenantId": "acme-corp",
  "data": {
    // Ereignisspezifischer Payload
  }
}

Das Feld data variiert je nach Ereignistyp und enthält die relevanten Entitätsdaten zum Zeitpunkt des Ereignisses.

Zugehörige Anleitungen

• Webhook-Integration — Entwicklerleitfaden — Einen Webhook-Consumer mit Signaturverifizierung erstellen
• Actions-Engine — Alternative für In-Flow-Logik (läuft während der Auth, nicht danach)
• Prüfprotokolle — Alle Authentifizierungsereignisse mit vollständigen Prüfpfaden anzeigen