Webhooks einrichten

Webhooks ermöglichen es deiner Anwendung, Echtzeit-HTTP-Benachrichtigungen zu empfangen, wenn Ereignisse in Auris auftreten, wie z. B. eine Benutzerregistrierung, ein fehlgeschlagener Login, eine zugewiesene Rolle oder eine erstellte Organisation. Anstatt die API nach Änderungen abzufragen, pusht Auris Event-Payloads an deinen Endpunkt, sobald etwas passiert.

Dieser Leitfaden führt dich durch das Erstellen eines Webhook-Empfängers, die Registrierung in der Auris-Console, die Verifizierung von Signaturen für die Sicherheit und die Behandlung von Fehlern.

Warum Webhooks

Ohne Webhooks müsste deine Anwendung regelmäßig Auris-APIs abfragen, um Änderungen zu erkennen. Dies ist ineffizient, führt zu Latenz und verschwendet auf beiden Seiten Ressourcen. Webhooks kehren das um: Auris informiert deine Anwendung sofort, wenn etwas passiert.

Häufige Anwendungsfälle:

• Benutzerdaten synchronisieren in deiner Datenbank, wenn ein Benutzer erstellt oder aktualisiert wird
• Onboarding-Workflows auslösen, wenn sich ein neuer Benutzer registriert
• Zugriff widerrufen in deinem System, wenn ein Benutzer deaktiviert oder gelöscht wird
• Audit-Logging durch Streaming von Ereignissen an dein SIEM
• Slack/Teams-Benachrichtigungen, wenn verdächtige Login-Aktivitäten erkannt werden

Schritt 1: Webhook-Endpunkt in deiner Anwendung erstellen

Dein Webhook-Endpunkt ist ein Standard-HTTP-POST-Handler, der JSON-Payloads von Auris empfängt. Hier ist ein vollständiges Express.js-Beispiel mit Signaturverifizierung:

import express from 'express'
import crypto from 'crypto'
 
const app = express()
 
// WICHTIG: Rohen Body für Signaturverifizierung verwenden
app.post(
  '/webhooks/auris',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-webhook-signature'] as string
    const timestamp = req.headers['x-webhook-timestamp'] as string
    const secret = process.env.AURIS_WEBHOOK_SECRET! // z.B. whsec_abc123...
 
    // 1. Signatur verifizieren
    if (!verifyWebhookSignature(req.body, signature, timestamp, secret)) {
      console.error('Webhook-Signaturverifizierung fehlgeschlagen')
      return res.status(401).json({ error: 'Ungültige Signatur' })
    }
 
    // 2. Ereignis parsen
    const event = JSON.parse(req.body.toString())
 
    // 3. Sofort 200 antworten — asynchron verarbeiten
    res.status(200).json({ received: true })
 
    // 4. Ereignis asynchron verarbeiten
    handleWebhookEvent(event).catch((err) =>
      console.error('Webhook-Handler-Fehler:', err)
    )
  }
)
 
function verifyWebhookSignature(
  body: Buffer,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Ablehnen, wenn Zeitstempel älter als 5 Minuten (Replay-Schutz)
  const eventTime = parseInt(timestamp, 10)
  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - eventTime) > 300) {
    return false
  }
 
  // Erwartete Signatur berechnen: HMAC-SHA256(timestamp.body)
  const payload = `${timestamp}.${body.toString()}`
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
 
  // Zeitkonstanter Vergleich zum Verhindern von Timing-Angriffen
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    )
  } catch {
    return false
  }
}
 
async function handleWebhookEvent(event: {
  type: string
  data: Record<string, unknown>
}) {
  switch (event.type) {
    case 'user.created':
      await syncUser(event.data)
      break
    case 'user.deleted':
      await removeUser(event.data)
      break
    case 'login.suspicious':
      await notifySecurityTeam(event.data)
      break
    default:
      console.log(`Unbehandelter Ereignistyp: ${event.type}`)
  }
}

Schritt 2: Webhook in der Auris-Console registrieren

1. Öffne die Auris-Console und navigiere zu Einstellungen → Webhooks
2. Klicke auf Webhook erstellen
3. Gib deine Endpunkt-URL ein (z. B. https://api.ihreapp.com/webhooks/auris)
4. Wähle die Ereignisse aus, die du empfangen möchtest (oder wähle “Alle Ereignisse”)
5. Klicke auf Erstellen

Auris generiert ein Signierungsgeheimnis mit dem Präfix whsec_. Kopiere diesen Wert sofort und speichere ihn sicher in deinen Umgebungsvariablen. Das vollständige Geheimnis wird nur einmal angezeigt.

Schritt 3: Webhook-Signaturen verifizieren

Jede Webhook-Zustellung von Auris enthält zwei Headers zur Verifizierung:

Die Signatur wird berechnet als:

HMAC-SHA256(whsec_secret, "${timestamp}.${rawBody}")

Verifizierungsalgorithmus

1. Extrahiere die X-Webhook-Signature- und X-Webhook-Timestamp-Header
2. Prüfe, ob der Zeitstempel innerhalb von 5 Minuten der aktuellen Zeit liegt (Replay-Schutz)
3. Konkateniere den Zeitstempel, einen wörtlichen Punkt (.) und den rohen Anfrage-Body
4. Berechne den HMAC-SHA256 dieses Strings mit deinem whsec_-Signierungsgeheimnis
5. Vergleiche deine berechnete Signatur mit der empfangenen Signatur mit einem zeitkonstanten Vergleich

import crypto from 'crypto'
 
export function verifyAurisWebhook(
  rawBody: string | Buffer,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  const ts = parseInt(timestamp, 10)
  if (isNaN(ts) || Math.abs(Date.now() / 1000 - ts) > 300) {
    return false
  }
 
  const body = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf-8')
  const payload = `${timestamp}.${body}`
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
 
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'utf-8'),
      Buffer.from(expected, 'utf-8')
    )
  } catch {
    return false
  }
}

Ereigniskatalog

Auris sendet Ereignisse in folgenden Kategorien:

Benutzer-Ereignisse

Login-Ereignisse

Rollen- und Berechtigungsereignisse

Organisations-Ereignisse

Beispiel-Payload

{
  "id": "evt_abc123def456",
  "type": "user.created",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "id": "usr_xyz789",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "emailVerified": false,
    "roles": [],
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

Fehler und Wiederholungsversuche behandeln

Wenn dein Endpunkt einen Nicht-2xx-Statuscode zurückgibt oder nicht innerhalb von 30 Sekunden antwortet, betrachtet Auris die Zustellung als fehlgeschlagen und wiederholt mit exponentiellem Backoff:

Webhooks testen

Console-Test-Schaltfläche

In der Auris-Console hat jeder Webhook eine Test-Schaltfläche, die ein synthetisches Ereignis an deinen Endpunkt sendet.

Lokale Entwicklung mit ngrok

Während der Entwicklung ist dein lokaler Server nicht öffentlich erreichbar. Verwende ein Tunneling-Tool wie ngrok:

# Lokalen Webhook-Server starten
node server.js
 
# In einem anderen Terminal ngrok starten
ngrok http 3000

ngrok stellt eine öffentliche URL bereit wie https://a1b2c3d4.ngrok-free.app. Verwende diese URL bei der Registrierung des Webhooks in der Console.

Best Practices

Sofort mit 200 antworten. Dein Endpunkt sollte HTTP 200 so schnell wie möglich zurückgeben, dann das Ereignis asynchron verarbeiten (z. B. durch Einreihen in eine Warteschlange).

Idempotenz implementieren. Jedes Ereignis enthält ein eindeutiges id-Feld. Speichere verarbeitete Ereignis-IDs und überspringe Duplikate:

async function handleWebhookEvent(event: { id: string; type: string; data: unknown }) {
  const exists = await db.processedWebhookEvent.findUnique({
    where: { eventId: event.id },
  })
  if (exists) {
    console.log(`Doppeltes Ereignis übersprungen: ${event.id}`)
    return
  }
 
  await processEvent(event)
 
  await db.processedWebhookEvent.create({
    data: { eventId: event.id, processedAt: new Date() },
  })
}

HTTPS-Endpunkte verwenden. Auris sendet Webhook-Payloads nur über HTTPS. HTTP-Endpunkte werden bei der Registrierung abgelehnt.

Geheimnisse regelmäßig rotieren. Verwende die Console oder API, um dein Webhook-Signierungsgeheimnis zu rotieren.

Verwandte Leitfäden

• Log Streaming — Audit-Logs an externe Dienste wie Datadog und Splunk streamen
• Actions-Engine — Benutzerdefinierte Logik während Authentifizierungsflows ausführen
• Angriffsschutz — Sicherheitspipeline und Suspicious-Login-Erkennung