Zuverlässiger Webhook-Empfänger: Signatur, Idempotenz, Queue und Retries

Prompt

Handle als Backend-Engineer mit Erfahrung in Integrationen und verteilten Systemen.

Ich muss Webhooks zuverlässig empfangen:
- Anbieter und Signaturverfahren: {{anbieter}}
- Relevante Ereignisse und was ich jeweils tue: {{ereignisse}}
- Stack: {{stack}}
- Verfügbares Queue-System: {{queue}}

Liefere:
1. Ein Textdiagramm des Ablaufs: Empfang, Prüfung, Speicherung, Einreihen, Verarbeitung, Retries und Dead-Letter-Queue.
2. Den Empfangsendpunkt:
   - Liest den Rohbody vor dem Parsen und prüft die HMAC-Signatur mit zeitkonstantem Vergleich.
   - Lehnt Anfragen mit Zeitstempel außerhalb eines kurzen Fensters ab, um Replay-Angriffe zu verhindern.
   - Speichert das Ereignis und antwortet innerhalb von Millisekunden mit 2xx; keine aufwendige Logik im Request.
3. Idempotenz: eine Ereignistabelle mit der Ereignis-ID des Anbieters als Unique Key, Zuständen (empfangen, in Arbeit, erledigt, fehlgeschlagen) und dem Vorgehen, wenn dasselbe Ereignis zweimal eintrifft.
4. Worker: Verarbeitung mit exponentiellem Backoff und Jitter, maximaler Versuchszahl, Unterscheidung zwischen vorübergehenden und dauerhaften Fehlern sowie Dead-Letter-Queue mit Möglichkeit zur erneuten Verarbeitung.
5. Reihenfolge: Umgang mit Ereignissen in falscher Reihenfolge (z. B. Version oder Zeitstempel der Ressource prüfen oder sie über die API des Anbieters neu abrufen).
6. Logging und Alerting: was protokolliert wird, ohne sensible Daten zu speichern, und welche Kennzahlen zu überwachen sind.
7. Tests: gültige und ungültige Signatur, doppeltes Ereignis, veralteter Zeitstempel, vorübergehender Fehler mit Erholung und dauerhafter Fehler, der in der Dead-Letter-Queue landet.
8. Lokales Testen (Tunnel oder Event-Weiterleitung), ohne das Secret preiszugeben.

Einschränkungen:
- Rate nicht das genaue Signaturformat oder die Header-Namen des Anbieters: Wenn ich sie nicht nenne, markiere sie mit [AUSFÜLLEN] und sag mir, wo ich sie in der Dokumentation finde.
- Das Secret kommt aus Umgebungsvariablen oder einem Secret-Manager, nie aus dem Code.
- Fehlen wichtige Informationen, frag nach, bevor du Code schreibst.

So verwenden Sie ihn

Anwendungsbeispiel

Beispielergebnis

Zahlungsdienst → POST /webhooks/zahlungen → Signatur + Zeitstempel prüfen → INSERT Ereignis (unique)
               → Commit → 200 → Celery: verarbeiten → Retries mit Backoff → Dead-Letter

@router.post("/webhooks/zahlungen")
async def empfangen(request: Request, db: AsyncSession = Depends(get_db)) -> dict:
    roh = await request.body()                        # roher Body, vor dem Parsen
    ts = request.headers.get("[AUSFÜLLEN: Zeitstempel-Header]", "")
    signatur = request.headers.get("[AUSFÜLLEN: Signatur-Header]", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        raise HTTPException(400, "Zeitstempel fehlt oder ist veraltet")

    # Format der signierten Nachricht laut Anbieter-Doku: [AUSFÜLLEN]
    erwartet = hmac.new(settings.webhook_secret.encode(),
                        f"{ts}.".encode() + roh, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(erwartet, signatur):   # Vergleich in konstanter Zeit
        raise HTTPException(400, "ungültige Signatur")

    ereignis = json.loads(roh)
    stmt = (insert(WebhookEvent)
            .values(provider_event_id=ereignis["id"], typ=ereignis["type"],
                    payload=ereignis, status="empfangen")
            .on_conflict_do_nothing(index_elements=["provider_event_id"])
            .returning(WebhookEvent.id))
    neue_id = (await db.execute(stmt)).scalar_one_or_none()
    await db.commit()
    if neue_id is not None:                           # Duplikat → nicht erneut einreihen
        ereignis_verarbeiten.delay(neue_id)
    return {"ok": True}

Wichtige Fakten

Kategorie

Programmierung & Entwicklung · APIs

Ausgabetyp

Code

Niveau

Experte

Entwickelt für

ChatGPT, Claude, Gemini und Microsoft Copilot

Verifiziert in

Redaktionelle Prüfung ausstehend

Variablen

Anbieter und Signatur, Ereignisse und Aktionen, Stack und Queue-System

Sprache

Deutsch

Preis

Kostenlos, ohne Anmeldung

Aktualisiert

07.11.2026

Häufig gestellte Fragen