Authon — Universelle Authentifizierungsplattform

Webhooks

Empfangen Sie Echtzeit-HTTP-Benachrichtigungen, wenn Authentifizierungsereignisse in Ihrem Projekt auftreten. Synchronisieren Sie Benutzer mit Ihrer Datenbank, senden Sie Willkommens-E-Mails oder lösen Sie Workflows aus, wenn Benutzer sich registrieren, anmelden oder gesperrt werden.

Was sind Webhooks?

Ein Webhook ist ein HTTP-Callback, den Ihr Server registriert, um Echtzeit-Ereignisbenachrichtigungen zu empfangen. Anstatt Authon abzufragen, ob ein Benutzer gelöscht oder gesperrt wurde, sendet Authon proaktiv eine POST-Anfrage an Ihre URL, sobald das Ereignis eintritt.

text

Benutzer im Authon-Dashboard gelöscht
  → Authon sendet POST /webhooks/authon
  → Ihr Server empfängt das Ereignis und entfernt den Benutzer aus Ihrer DB

Wie Webhooks funktionieren

Wenn ein Ereignis in Ihrem Authon-Projekt auftritt, sendet die API eine POST-Anfrage an Ihren registrierten Endpunkt mit einer JSON-Nutzlast. Jede Anfrage enthält einen X-Authon-Signature-Header mit dem Präfix v1= — eine HMAC-SHA256-Signatur, die über timestamp.body mit Ihrem Webhook-Signing-Secret berechnet wurde. Verifizieren Sie diese Signatur immer, bevor Sie das Ereignis verarbeiten.

Ein Ereignis tritt in Authon auf (z. B. ein Benutzer registriert sich)

Authon signiert die Nutzlast mit HMAC-SHA256 unter Verwendung Ihres Webhook-Secrets

Authon sendet eine POST-Anfrage an Ihre Endpunkt-URL

Ihr Server verifiziert die Signatur und verarbeitet das Ereignis

Ihr Server antwortet mit 2xx, um den Empfang zu bestätigen

Webhook einrichten

1
Navigieren Sie zu Dashboard → Webhooks → Webhook hinzufügen
2
Geben Sie Ihre Endpunkt-URL ein — muss öffentlich über HTTPS erreichbar sein
3
Wählen Sie die Ereignisse aus, die Sie empfangen möchten
4
Kopieren Sie das Signing-Secret — wird nur einmal angezeigt, sicher aufbewahren
5
Setzen Sie AUTHON_WEBHOOK_SECRET in Ihrer Server-Umgebung

Ereignistypen

Ereignis	Auslöser
user.created	Ein neuer Benutzer schließt die Registrierung ab
user.updated	Das Profil eines Benutzers wird aktualisiert
user.deleted	Ein Benutzerkonto wird dauerhaft gelöscht
user.signin	Ein Benutzer meldet sich an (E-Mail oder OAuth)
user.signout	Ein Benutzer meldet sich ab
user.banned	Ein Benutzer wird von einem Administrator gesperrt
user.unbanned	Die Sperre eines Benutzers wird aufgehoben
session.created	Eine neue Sitzung wird erstellt (Anmeldung, Token-Aktualisierung)
session.revoked	Eine Sitzung wird widerrufen (Abmeldung, Admin-Widerruf)

Nutzlastformat

Jede Webhook-Nutzlast ist ein JSON-Objekt mit einer konsistenten Top-Level-Struktur. Das data Feld enthält ereignisspezifische Details.

json

{
  "event": "user.created",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "Jane Doe",
      "emailVerified": false,
      "isBanned": false,
      "publicMetadata": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    }
  },
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Fürsession.*Ereignisse enthält das dataFeld auch ein sessionObjekt mit id, ipAddress und userAgent.

Signaturverifizierung

Jede Webhook-Anfrage enthält einen X-Authon-Signature Header mit dem Format v1=<hex_digest>. Die Signatur wird als HMAC-SHA256 über timestamp.rawBody mit Ihrem Webhook-Secret berechnet. Vergleichen Sie das Ergebnis mit zeitkonstanter Gleichheit.

Header	Format	Beschreibung
X-Authon-Signature	v1={hmac_sha256}	HMAC-SHA256-Signatur zur Verifizierung des Anfrage-Ursprungs
X-Authon-Timestamp	ISO 8601	ISO 8601-Zeitstempel des Zeitpunkts, zu dem das Ereignis gesendet wurde
X-Authon-Event	user.created	Der Ereignistyp (z. B. user.created, session.revoked)

Verwenden Sie immer den rohen Body-Buffer zur Verifizierung, nicht einen geparsten JSON-String. Die json() Middleware von Express serialisiert den Body erneut, was Leerzeichen verändern und die Signatur ungültig machen kann.

Node.js-Beispiel

routes/webhooks.ts

import { createHmac, timingSafeEqual } from "crypto";
import express from "express";

const router = express.Router();

function verifySignature(
  rawBody: Buffer,
  signature: string,
  secret: string,
  timestamp: string,
): boolean {
  const payload = `${timestamp}.${rawBody.toString()}`;
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  const actual = signature.replace("v1=", "");

  const expectedBuf = Buffer.from(expected, "hex");
  const actualBuf = Buffer.from(actual, "hex");

  return (
    expectedBuf.length === actualBuf.length &&
    timingSafeEqual(expectedBuf, actualBuf)
  );
}

router.post(
  "/webhooks/authon",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-authon-signature"] as string;
    const timestamp = req.headers["x-authon-timestamp"] as string; // ISO 8601
    const eventType = req.headers["x-authon-event"] as string;
    const webhookSecret = process.env.AUTHON_WEBHOOK_SECRET!;

    if (!verifySignature(req.body, signature, webhookSecret, timestamp)) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    const { event, data } = JSON.parse(req.body.toString());

    switch (eventType) {
      case "user.created":
        // Sync new user to your database
        break;
      case "user.deleted":
        // Remove user from your database
        break;
      case "user.updated":
        // Update user data
        break;
      case "user.banned":
        // Revoke app-level access
        break;
    }

    res.status(200).json({ received: true });
  }
);

export default router;

Das SDK verwenden

Das@authon/node SDK bietet einen integrierten Verify-Helfer, der den zeitkonstanten Vergleich für Sie übernimmt:

import { AuthonBackend } from "@authon/node";

const authon = new AuthonBackend(process.env.AUTHON_SECRET_KEY!);

router.post(
  "/webhooks/authon",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-authon-signature"] as string;
    const timestamp = req.headers["x-authon-timestamp"] as string;

    let event: Record<string, unknown>;
    try {
      event = authon.webhooks.verify(
        req.body,
        signature,
        timestamp,
        process.env.AUTHON_WEBHOOK_SECRET!,
      );
    } catch {
      return res.status(401).json({ error: "Invalid signature" });
    }

    console.log("Verified event:", event.event);
    res.json({ received: true });
  }
);

Wiederholungsrichtlinie

Wenn Ihr Endpunkt einen Nicht-2xx-Statuscode zurückgibt oder nicht innerhalb von 10 Sekundenantwortet, wiederholt Authon die Zustellung mit exponentiell ansteigendem Backoff. Maximal 3 Versuche insgesamt.

Versuch	Verzögerung	Kumulative Zeit
Initial	—	0s
1. Wiederholung	1 second	~1s
2. Wiederholung	2 seconds	~3s

Anwendungsfälle

Benutzer mit Ihrer Datenbank synchronisieren

Halten Sie die Benutzertabelle Ihrer App mit Authon synchron. Hören Sie auf user.created, user.updated und user.deleted, um Änderungen automatisch zu spiegeln.

Willkommens-E-Mails senden

Lösen Sie eine Willkommens-E-Mail oder eine Onboarding-Sequenz aus, wenn user.created ausgelöst wird. Verwenden Sie die E-Mail und den Anzeigenamen des Benutzers aus der Ereignisnutzlast.

Sperren in Echtzeit durchsetzen

Wenn user.banned ausgelöst wird, widerrufen Sie sofort App-Level-Zugriffstoken oder Cache-Einträge, damit der Benutzer Ihren Dienst nicht weiter nutzen kann.

Best Practices

Signatur immer verifizieren

Überspringen Sie die Signaturverifizierung nie. Jeder kann eine POST-Anfrage an Ihren Endpunkt senden — die Verifizierung beweist, dass die Anfrage von Authon stammt.

Rohen Body-Parsing verwenden

Die Signaturverifizierung erfordert die exakten Rohbytes des Anfrage-Bodys. Vermeiden Sie JSON-Middleware auf Webhook-Routen.

Schnell antworten, asynchron verarbeiten

Geben Sie sofort 200 zurück und verarbeiten Sie das Ereignis asynchron. Authon wiederholt den Versuch, wenn Ihr Endpunkt länger als 10s benötigt.

Handler idempotent gestalten

Sie können das gleiche Ereignis aufgrund von Wiederholungen mehr als einmal empfangen. Verwenden Sie den Ereigniszeitstempel zur Deduplizierung — speichern Sie verarbeitete Ereignisse in Ihrer DB.

Secrets regelmäßig rotieren

Generieren Sie alle 90 Tage ein neues Signing-Secret aus dem Dashboard. Aktualisieren Sie AUTHON_WEBHOOK_SECRET in Ihrer Deployment ohne Ausfallzeit.

Alle Ereignisse anzeigen Benutzer-Synchronisations-Anleitung API-Referenz