> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Erhalten Sie Echtzeit-HTTP-Benachrichtigungen, wenn Ereignisse in Ihrem Truthlocks-Mandanten auftreten.

Webhooks ermöglichen Ihrer Anwendung, automatische Benachrichtigungen zu erhalten, wenn Ereignisse in Ihrem Truthlocks-Konto auftreten – zum Beispiel, wenn eine Bestätigung geprägt wird, ein Schlüssel rotiert wird oder eine Verifizierung fehlschlägt. Anstatt die API auf Änderungen abzufragen, empfängt Ihr Server eine HTTP-POST-Anfrage mit den Ereignisdetails.

## Funktionsweise

**1. Einen Endpunkt registrieren**

Fügen Sie einen Webhook-Endpunkt unter **Einstellungen > Webhooks** in der [Mandantenkonsole](https://console.truthlocks.com) hinzu. Geben Sie eine öffentlich erreichbare HTTPS-URL an und wählen Sie aus, welche Ereignistypen Sie empfangen möchten.

**2. Ereignisse empfangen**

Wenn ein passendes Ereignis eintritt, sendet Truthlocks eine HTTP POST-Anfrage an Ihre URL mit einer JSON-Nutzlast, die das Ereignis beschreibt.

**3. Signatur verifizieren**

Jede Anfrage enthält eine HMAC-SHA256-Signatur im `X-Truthlocks-Signature`-Header. Verifizieren Sie diese mit dem Endpunkt-Geheimnis, um zu bestätigen, dass die Anfrage von Truthlocks stammt.

**4. Mit 200 antworten**

Geben Sie einen HTTP-`200` Statuscode zurück, um den Empfang zu bestätigen. Wenn Ihr Endpunkt fehlschlägt oder eine Zeitüberschreitung auftritt, versucht Truthlocks es mit exponentiellem Backoff erneut.

## Ereignistypen

Ereignisse werden in Kategorien gruppiert. Sie können einzelne Ereignisse abonnieren oder einen Platzhalter (`attestation.*`) verwenden, um alle Ereignisse in einer Kategorie zu erhalten.

| Kategorie | Ereignis | Auslöser |
| :- | :- | :- |
| **Bestätigungen** | `attestation.created` | Eine neue Bestätigung wird geprägt |
| | `attestation.revoked` | Eine Bestätigung wird widerrufen |
| | `attestation.expired` | Eine Bestätigung erreicht ihr Ablaufdatum |
| | `attestation.superseded` | Eine Bestätigung wird durch eine neuere Version ersetzt |
| **Verifizierung** | `verification.completed` | Eine Verifizierungsprüfung ist erfolgreich |
| | `verification.failed` | Eine Verifizierungsprüfung schlägt fehl |
| **Aussteller** | `issuer.created` | Ein neuer Aussteller wird registriert |
| | `issuer.updated` | Das Profil oder die Einstellungen eines Ausstellers ändern sich |
| | `issuer.suspended` | Ein Aussteller wird gesperrt |
| **Schlüssel** | `key.created` | Ein Signaturschlüssel wird registriert |
| | `key.rotated` | Ein Signierschlüssel wird rotiert |
| | `key.revoked` | Ein Signierschlüssel wird widerrufen |
| | `key.compromised` | Ein Schlüssel wird als kompromittiert gemeldet |
| **Team** | `team.member_invited` | Eine Teameinladung wird gesendet |
| | `team.member_joined` | Ein Teammitglied nimmt eine Einladung an |
| | `team.member_removed` | Ein Teammitglied wird entfernt |
| | `team.role_changed` | Die Rolle eines Teammitglieds wird aktualisiert |
| **Abrechnung** | `billing.subscription.created` | Ein neues Abonnement wird erstellt |
| | `billing.subscription.updated` | Ein Abonnement wird geändert |
| | `billing.invoice.created` | Eine neue Rechnung wird generiert |
| | `billing.usage.threshold` | Ein Nutzungsschwellenwert wird erreicht |
| **Verbraucher** | `consumer.content.protected` | Ein Verbraucher schützt neue Inhalte |
| **Risikosignale** | `risk.signal.created` | Ein Risikosignal wird erfasst (jeder Erkennungspfad) |
| | `risk.signal.escalated` | Ein Risikosignalwert überschreitet den automatischen Überprüfungsschwellenwert |
| **Belege** | `receipt.created` | Ein neuer Beleg wird geprägt |
| | `receipt.revoked` | Ein Beleg wird widerrufen |
| | `receipt.type.created` | Ein neuer Belegtyp wird erstellt |
| | `receipt.type.deprecated` | Ein Belegtyp wird als veraltet markiert |
| **Sicherheit** | `security.password_changed` | Ein Benutzer ändert sein Passwort |
| | `security.api_key_compromised` | Ein API-Schlüssel wird als kompromittiert markiert |
| | `security.suspicious_activity` | Verdächtige Kontoaktivitäten werden erkannt |

### Wildcard-Filter

Verwenden Sie `category.*`, um jedes Ereignis in einer Kategorie zu abonnieren. Zum Beispiel entspricht `attestation.*` den Werten `attestation.created`, `attestation.revoked`, `attestation.expired` und `attestation.superseded`.

## Endpunktlimits nach Plan

Die Anzahl der Webhook-Endpunkte, die Sie erstellen können, hängt von Ihrer Planstufe ab:

| Plan | Endpunktlimit |
| :- | :- |
| Kostenlos | 1 |
| Starter | 3 |
| Geschäftlich | 10 |
| Enterprise | 25 |

Benötigen Sie weitere Endpunkte? Kontaktieren Sie Ihren Account Manager oder aktualisieren Sie Ihren Plan unter **Einstellungen > Abrechnung**.

## Einen Endpunkt erstellen

1. Gehen Sie in der Mandantenkonsole zu **Einstellungen > Webhooks**.
2. Klicken Sie auf **Endpunkt hinzufügen**.
3. Geben Sie einen Namen, Ihre HTTPS-Ziel-URL ein und wählen Sie die Ereignistypen aus, die Sie empfangen möchten.
4. Klicken Sie auf **Erstellen**.

Die Konsole zeigt Ihr Endpunkt-Geheimnis einmal an. Kopieren Sie es sofort – Sie können es später nicht mehr abrufen.

### Über die API

```http Request theme={null}
POST /v1/webhooks/endpoints
X-API-Key: tl_live_...
Content-Type: application/json

{
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "event_filters": ["attestation.*", "verification.completed"]
}
```

```json Response theme={null}
{
  "id": "ep_abc123",
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "status": "active",
  "secret": "whsec_...",
  "event_filters": ["attestation.*", "verification.completed"],
  "created_at": "2026-03-25T12:00:00Z"
}
```

### Endpunkte auflisten

Rufen Sie alle Webhook-Endpunkte für Ihren Mandanten ab:

```http Request theme={null}
GET /v1/webhooks/endpoints
X-API-Key: tl_live_...
```

Die vollständige [API-Referenz](https://docs.truthlocks.com/de/api-reference/webhooks/list-endpoints.md) für Details zur Antwort finden Sie hier.

## Signaturen verifizieren

Jede Webhook-Anfrage enthält einen Signatur-Header zur Verifizierung. Verifizieren Sie Signaturen immer, bevor Sie Ereignisse verarbeiten.

**Signaturformat:**

```
X-Truthlocks-Signature: t=1710000000,v1=a1b2c3d4e5f6...
```

Wobei `t` der Unix-Zeitstempel und `v1` der HMAC-SHA256-Hex-Digest ist.

**Verifizierungsschritte:**

1. Extrahieren Sie `t` (Zeitstempel) und `v1` (Signatur) aus dem Header.
2. Lehnt die Anfrage ab, wenn der Zeitstempel älter als 5 Minuten ist.
3. Verketten Sie `{timestamp}.{raw_request_body}`, um den Signaturstring zu bilden.
4. Berechnen Sie HMAC-SHA256 des Signaturstrings mit Ihrem Endpunkt-Geheimnis.
5. Vergleichen Sie den berechneten Digest mit `v1` unter Verwendung eines Vergleichs mit konstanter Zeit.

```typescript verify-webhook.ts theme={null}
import crypto from "crypto";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/truthlock", (req, res) => {
  const sigHeader = req.headers["x-truthlocks-signature"] as string;
  if (!sigHeader) return res.status(401).send("Missing signature");

  const parts = Object.fromEntries(
    sigHeader.split(",").map((p) => p.split("=") as [string, string])
  );
  const timestamp = parts["t"];
  const signature = parts["v1"];

  // Reject stale requests (5-minute window)
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return res.status(401).send("Timestamp expired");

  // Compute expected signature
  const signingString = `${timestamp}.${req.body.toString()}`;
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(signingString)
    .digest("hex");

  // Constant-time comparison
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString());
  console.log("Received event:", event.type);

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

```go verify-webhook.go theme={null}
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"math"
	"net/http"
	"strconv"
	"strings"
	"time"
)

func verifyWebhook(r *http.Request, secret string) ([]byte, error) {
	sig := r.Header.Get("X-Truthlocks-Signature")
	if sig == "" {
		return nil, fmt.Errorf("missing signature header")
	}

	parts := map[string]string{}
	for _, p := range strings.Split(sig, ",") {
		kv := strings.SplitN(p, "=", 2)
		if len(kv) == 2 {
			parts[kv[0]] = kv[1]
		}
	}

	ts, _ := strconv.ParseInt(parts["t"], 10, 64)
	age := math.Abs(float64(time.Now().Unix() - ts))
	if age > 300 {
		return nil, fmt.Errorf("timestamp expired")
	}

	body, err := io.ReadAll(r.Body)
	if err != nil {
		return nil, err
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(fmt.Sprintf("%d.%s", ts, body)))
	expected := hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(parts["v1"]), []byte(expected)) {
		return nil, fmt.Errorf("invalid signature")
	}

	return body, nil
}
```

```python verify_webhook.py theme={null}
import hashlib
import hmac
import time
from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/webhooks/truthlock", methods=["POST"])
def handle_webhook():
    sig_header = request.headers.get("X-Truthlocks-Signature", "")
    parts = dict(p.split("=", 1) for p in sig_header.split(","))

    timestamp = parts.get("t", "")
    signature = parts.get("v1", "")

    # Reject stale requests
    if abs(time.time() - int(timestamp)) > 300:
        abort(401, "Timestamp expired")

    # Compute expected signature
    signing_string = f"{timestamp}.{request.get_data(as_text=True)}"
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        signing_string.encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401, "Invalid signature")

    event = request.get_json()
    print(f"Received event: {event['type']}")
    return {"received": True}
```

> [!WARNING]
>
> Verwenden Sie immer eine Vergleichsfunktion mit konstanter Zeit (wie `crypto.timingSafeEqual` oder `hmac.compare_digest`), um Timing-Angriffe zu verhindern.

## Anfrage-Header

Jede Webhook-Zustellung enthält diese Header:

| Header | Beschreibung |
| :- | :- |
| `Content-Type` | `application/json` |
| `User-Agent` | `Truthlocks-Webhook-Service/1.0` |
| `X-Truthlocks-Event-Id` | Eindeutige Kennung für das Ereignis |
| `X-Truthlocks-Event-Type` | Ereignistyp (z. B. `attestation.created`) |
| `X-Truthlocks-Timestamp` | Unix-Zeitstempel des Zustellversuchs |
| `X-Truthlocks-Signature` | HMAC-SHA256-Signatur zur Verifizierung |

## Wiederholungsverhalten

Wenn Ihr Endpunkt einen Nicht-2xx-Statuscode zurückgibt oder nicht innerhalb von 5 Sekunden antwortet, versucht Truthlocks die Zustellung mit exponentiellem Backoff erneut:

| Versuch | Ungefähre Verzögerung |
| :- | :- |
| 1. Wiederholung | \~1 Sekunde |
| 2. Wiederholung | \~2 Sekunden |
| 3. Wiederholung | \~4 Sekunden |
| 4. Wiederholung | \~16 Sekunden |
| 5. Wiederholung | \~1 Minute |
| 6. Wiederholung | \~2 Minuten |
| 7. Wiederholung | \~5 Minuten (max) |

Verzögerungen beinhalten bis zu 30 % Jitter. Nach insgesamt 8 Versuchen (1 initialer + 7 Wiederholungen) wird die Zustellung als fehlgeschlagen markiert.

Sie können Zustellversuche und Fehlerdetails unter **Einstellungen > Webhooks** anzeigen, indem Sie auf einen Endpunkt klicken, oder sie über die API abfragen:

```http Request theme={null}
GET /v1/webhooks/endpoints/{id}/deliveries
X-API-Key: tl_live_...
```

Details zur Antwort finden Sie in der [API-Referenz für Lieferungen auflisten](https://docs.truthlocks.com/de/api-reference/webhooks/list-deliveries.md).

## Rotierende Geheimnisse

Wenn Ihr Webhook-Geheimnis kompromittiert ist, rotieren Sie es sofort:

1. Gehen Sie in der Mandantenkonsole zu **Einstellungen > Webhooks** und klicken Sie auf den Endpunkt.
2. Klicken Sie auf **Geheimnis rotieren**.
3. Kopieren Sie das neue Geheimnis – das alte Geheimnis funktioniert sofort nicht mehr.

Sie können auch über die API rotieren:

```http Request theme={null}
POST /v1/webhooks/endpoints/{id}/rotate
X-API-Key: tl_live_...
```

## Webhooks testen

Senden Sie ein Testereignis, um zu überprüfen, ob Ihr Endpunkt funktioniert:

1. Gehen Sie in der Mandantenkonsole zu **Einstellungen > Webhooks** und klicken Sie auf den Endpunkt.
2. Klicken Sie auf **Test senden**.
3. Ein `webhook.test`-Ereignis wird über die vollständige Signatur- und Zustellpipeline an Ihre URL gesendet.

Über die API:

```http Request theme={null}
POST /v1/webhooks/test-delivery
X-API-Key: tl_live_...
Content-Type: application/json

{
  "endpoint_id": "ep_abc123",
  "event_type": "webhook.test",
  "payload": { "status": "ok", "source": "test-delivery" }
}
```

Die Felder `event_type` und `payload` sind optional – sie verwenden standardmäßig `webhook.test` und eine grundlegende Status-Payload, wenn sie weggelassen werden.

## Benachrichtigungen über Risikosignale

Sie können Echtzeit-Webhook-Benachrichtigungen erhalten, wann immer ein Risikosignal von einem der fünf [Anti-Fraud Identity Firewall](https://docs.truthlocks.com/de/guides/risk-signals.md) Erkennungspfade erstellt wird – direkte Aufnahme, Ereignisnormalisierung, Deepfake-Scanning, ATO-Erkennung und Geschwindigkeitsbewertung.

Abonnieren Sie `risk.signal.*`, um alle Risikosignalereignisse zu erhalten, oder abonnieren Sie `risk.signal.created` oder `risk.signal.escalated` einzeln.

### Beispiel-Payload

```json theme={null}
{
  "id": "evt_r1s2k3...",
  "type": "risk.signal.created",
  "created_at": "2027-07-24T09:15:00Z",
  "data": {
    "signal_id": "a1b2c3d4-...",
    "signal_source": "velocity",
    "signal_type": "velocity",
    "risk_score": 72,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f"
  }
}
```

### Reaktion auf Risikosignale

Verwenden Sie Risikosignal-Webhooks, um automatisierte Antworten auszulösen – eine Benutzersitzung blockieren, Ihr Sicherheitsteam benachrichtigen oder einen Betrugsfall eskalieren – ohne die API abzufragen.

```javascript theme={null}
app.post("/webhooks/truthlock", (req, res) => {
  const event = JSON.parse(req.body.toString());

  if (event.type === "risk.signal.created") {
    const { risk_score, subject_id, signal_type } = event.data;

    if (risk_score >= 80) {
      // Critical — block immediately and alert security
      blockSubject(subject_id);
      notifySecurityTeam(event.data);
    } else if (risk_score >= 60) {
      // High — throttle and log for review
      throttleSubject(subject_id);
    }
  }

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

> [!NOTE]
>
> Risikosignal-Webhooks werden für Signale ausgelöst, die von allen fünf Erkennungspfaden erstellt wurden. Das Feld `signal_source` in der Nutzlast gibt an, welcher Pfad das Signal generiert hat – `external`, `event_normalization`, `deepfake`, `ato` oder `velocity`.

## Best Practices

> [!TIP]
>
> Reagieren Sie schnell auf Webhooks. Führen Sie Ihre aufwendige Verarbeitung asynchron durch, nachdem Sie eine `200`-Antwort zurückgegeben haben, um Timeouts und Wiederholungsversuche zu vermeiden.

* **Jede Signatur verifizieren.** Überspringen Sie niemals die Signaturverifizierung, auch nicht in der Entwicklung.
* **Verwenden Sie eine Nachrichtenwarteschlange.** Reihen Sie eingehende Ereignisse ein und verarbeiten Sie sie in einem Worker, um das Blockieren der HTTP-Antwort zu vermeiden.
* **Duplikate behandeln.** Verwenden Sie den `X-Truthlocks-Event-Id` Header, um Ereignisse bei Wiederholungsversuchen zu deduplizieren.
* **Lieferfehler überwachen.** Überprüfen Sie regelmäßig den Tab „Lieferungen“ in der Konsole auf fehlgeschlagene oder tote Lieferungen.
* **Geheimnisse sicher aufbewahren.** Speichern Sie Ihr Webhook-Geheimnis in Umgebungsvariablen, nicht im Quellcode.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.