Symfony: eingehende Webhooks empfangen und HMAC-Signaturen verifizieren

1. Warum ein dedizierter Controller für Webhook-Endpunkte nötig ist

Ein Webhook-Endpunkt unterscheidet sich fundamental von einem normalen API-Endpunkt, der von einem eingeloggten Nutzer oder einer authentifizierten API-Anwendung aufgerufen wird. Der externe Dienst, etwa ein Zahlungsanbieter oder eine Versanddienstleistung, sendet die Anfrage ohne klassische Session oder Bearer-Token, sondern signiert stattdessen den Payload kryptografisch und legt die Signatur in einen eigenen HTTP-Header. Ein dedizierter Controller pro Webhook-Quelle, statt eines generischen Endpunkts für mehrere Anbieter, hat den Vorteil, dass die jeweiligen Signatur-Header, Secrets und Verarbeitungslogik pro Anbieter klar getrennt bleiben und sich unabhängig voneinander testen und pflegen lassen.

Wichtig ist außerdem, dass ein Webhook-Controller unbedingt von der regulären Firewall-Konfiguration der Anwendung ausgenommen werden muss, denn der Endpunkt kann naturgemäß keine Symfony-Session oder CSRF-Token besitzen, wie sie ein normaler, browserbasierter Endpunkt erwartet. Stattdessen ersetzt die HMAC-Signatur diese Mechanismen vollständig als Authentizitäts- und Integritätsnachweis, weshalb die Sicherheit des gesamten Endpunkts direkt und ausschließlich von der Korrektheit dieser Signaturprüfung abhängt.

2. Ein dedizierter Controller für Webhook-Endpunkte in der Praxis

Das folgende Beispiel zeigt einen Controller für einen GitHub-artigen Webhook, der die Signatur aus dem Header X-Hub-Signature-256 liest und mit einer selbst berechneten HMAC-SHA256-Signatur des rohen Request-Bodys vergleicht. Entscheidend ist, dass für die Berechnung der Signatur ausschließlich der unveränderte, rohe Body über getContent() verwendet wird, denn selbst eine minimale Abweichung wie ein zusätzliches Leerzeichen oder eine andere Feldreihenfolge nach einer erneuten JSON-Kodierung würde die berechnete Signatur verändern und die Verifikation fälschlich scheitern lassen.

Der injizierte webhookSecret stammt idealerweise aus dem Secrets-Vault oder einer Umgebungsvariable und niemals aus Klartext-Code, denn wer dieses Geheimnis kennt, kann beliebige, gefälschte Payloads mit einer gültigen Signatur versehen. Bei einem Signatur-Mismatch liefert der Controller bewusst nur eine generische 401-Antwort ohne Details über den Grund des Fehlschlags, um einem Angreifer keine Informationen zu liefern, die das Erraten des Secrets erleichtern könnten, protokolliert den Vorfall aber serverseitig für die eigene Nachvollziehbarkeit.

<?php

declare(strict_types=1);

namespace App\Controller\Webhook;

use Psr\Log\LoggerInterface;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class GithubWebhookController
{
    public function __construct(
        private readonly string $webhookSecret,
        private readonly LoggerInterface $logger,
    ) {
    }

    #[Route('/webhooks/github', methods: ['POST'])]
    public function __invoke(Request $request): Response
    {
        $payload = $request->getContent();
        $signatureHeader = $request->headers->get('X-Hub-Signature-256', '');

        $expected = 'sha256=' . hash_hmac('sha256', $payload, $this->webhookSecret);

        if (!hash_equals($expected, $signatureHeader)) {
            $this->logger->warning('Webhook signature mismatch.');

            return new JsonResponse(['error' => 'invalid signature'], Response::HTTP_UNAUTHORIZED);
        }

        // ... verified payload wird hier verarbeitet, inklusive Idempotenz-Prüfung

        return new JsonResponse(['status' => 'accepted'], Response::HTTP_ACCEPTED);
    }
}

3. hash_hmac() und hash_equals() gegen Timing-Angriffe

hash_hmac() berechnet aus einem Payload und einem geheimen Schlüssel einen kryptografischen Hash, der ohne Kenntnis des Schlüssels praktisch nicht fälschbar ist, weil bereits eine minimale Änderung am Payload zu einem völlig anderen Hash-Wert führt. Entscheidend ist aber nicht nur die Berechnung, sondern auch der Vergleich der beiden Hash-Werte: Ein naiver Vergleich mit dem Operator === oder der Funktion strcmp() bricht bei den meisten PHP-Implementierungen beim ersten abweichenden Byte ab, was einem Angreifer theoretisch erlaubt, über winzige Zeitunterschiede im Antwortverhalten Byte für Byte den korrekten Hash-Wert zu erraten, ein klassischer Timing-Angriff.

hash_equals() vergleicht dagegen immer die volle Länge beider Strings in konstanter Zeit, unabhängig davon, an welcher Position ein Unterschied liegt, und macht dadurch das Ausmessen von Zeitunterschieden für einen Angreifer wertlos. Diese Funktion ist speziell für genau diesen Anwendungsfall in PHP eingeführt worden und sollte für jeden sicherheitsrelevanten String-Vergleich verwendet werden, nicht nur für HMAC-Signaturen, sondern etwa auch für den Vergleich von API-Schlüsseln oder Session-Token. Ein häufiger, subtiler Fehler ist, die Parameter-Reihenfolge von hash_equals() zu verwechseln: Der erste Parameter sollte immer der bekannte, vertrauenswürdige Wert sein, der zweite der vom Nutzer oder externen Dienst gelieferte Wert.

4. Die Symfony-Webhook-Komponente im Vergleich zur eigenen Implementierung

Symfony bietet seit einigen Versionen eine eigene Webhook-Komponente an, die eng mit dem RemoteEvent-System und den Mailer- und Notifier-Brücken verzahnt ist und primär für vorgefertigte Integrationen wie Mailgun-, Postmark- oder Mailjet-Bounce-Benachrichtigungen gedacht ist. Die Komponente stellt dafür einen generischen WebhookController bereit, der eingehende Anfragen an einen registrierten RequestParser weiterleitet, welcher wiederum die Signaturprüfung für den jeweiligen Anbieter kapselt und daraus ein RemoteEvent-Objekt erzeugt, das anschließend über den Symfony Messenger weiterverarbeitet werden kann.

Für generische, selbst definierte Webhooks von Drittanbietern wie Stripe, GitHub oder einem eigenen internen Microservice ist dieser Mechanismus in der Praxis aber oft nicht die passendste Wahl, weil er eng auf das RemoteEvent-Konzept zugeschnitten ist und für jeden neuen Anbieter einen eigenen RequestParser voraussetzt, der die volle Flexibilität eines eigenen Controllers gar nicht unbedingt einspart. Die meisten Projekte fahren deshalb besser mit einem eigenen, schlanken Controller wie im obigen Beispiel, der direkt auf die eigene Domain-Logik zugeschnitten ist, während die Symfony-Webhook-Komponente vor allem dann sinnvoll ist, wenn ohnehin bereits eine Mailer- oder Notifier-Brücke mit vorgefertigtem RequestParser für den jeweiligen Anbieter existiert.

5. Idempotenz bei wiederholten Webhook-Zustellungen

Nahezu jeder Webhook-Anbieter garantiert nur At-Least-Once-Zustellung, nicht Exactly-Once, was bedeutet, dass dasselbe Event bei einem Netzwerkfehler, einem verzögerten Antwort-Timeout oder einer internen Retry-Logik des Anbieters mehrfach an denselben Endpunkt gesendet werden kann. Verarbeitet der eigene Code ein Event bei jeder Zustellung erneut vollständig, kann das zu doppelt verbuchten Zahlungen, doppelt versendeten Benachrichtigungen oder inkonsistenten Datenbankzuständen führen, je nachdem, welche fachliche Aktion das Webhook-Event auslöst.

Die robuste Lösung ist, jedes Event anhand einer vom Anbieter mitgelieferten, eindeutigen Event-ID zu identifizieren, diese ID in einer eigenen Datenbanktabelle mit einem UNIQUE-Constraint zu speichern und den eigentlichen Verarbeitungsschritt nur auszuführen, wenn das Einfügen dieser ID tatsächlich erfolgreich war. Schlägt das Einfügen wegen eines Constraint-Verstoßes fehl, wurde das Event bereits verarbeitet, und der Controller kann sofort mit dem ursprünglichen Erfolgsstatus antworten, ohne die fachliche Logik ein zweites Mal auszuführen. Dieser Ansatz ist robuster als ein einfacher Cache-basierter Dedup-Mechanismus, weil ein Datenbank-Constraint auch bei gleichzeitigen, parallelen Zustellungen desselben Events zuverlässig nur eine einzige Verarbeitung garantiert.

6. Idempotenz-Prüfung transaktional mit der eigentlichen Verarbeitung verbinden

Ein häufiger, subtiler Fehler ist, die Event-ID zwar zu speichern, aber die eigentliche fachliche Verarbeitung als separaten, nicht-transaktionalen Schritt danach auszuführen. Schlägt die fachliche Verarbeitung fehl, nachdem die Event-ID bereits erfolgreich gespeichert wurde, wird ein späterer, berechtigter Retry-Versuch des Anbieters fälschlich als Duplikat erkannt und ignoriert, obwohl das Event nie erfolgreich verarbeitet wurde. Die korrekte Lösung ist, das Einfügen der Event-ID und die eigentliche fachliche Verarbeitung innerhalb derselben Datenbanktransaktion auszuführen, sodass entweder beides zusammen committet wird oder bei einem Fehler beides zusammen zurückgerollt wird.

In Symfony bietet sich dafür die Verwendung eines eigenen EntityManager-Transaktionsblocks an, in dem zuerst die Event-ID per persist() und flush() gespeichert wird, gefolgt von der eigentlichen fachlichen Logik innerhalb derselben Transaktion. Alternativ, insbesondere bei rechenintensiver oder langlaufender Verarbeitung, empfiehlt sich eine Trennung über den Symfony Messenger: Der Webhook-Controller speichert nur die Event-ID transaktional und stößt danach einen asynchronen Message-Handler an, der die eigentliche, potenziell langsamere Verarbeitung übernimmt, während der Controller selbst schnell mit Statuscode 202 Accepted antwortet, was viele Webhook-Anbieter ohnehin als Timeout-Grenze für die Antwort erwarten.

7. Häufige Fehler bei der Signaturprüfung in der Praxis

Ein besonders häufiger Fehler entsteht, wenn ein Symfony-EventListener oder ein globaler Body-Parser den Request-Body bereits vor dem Webhook-Controller konsumiert oder als JSON dekodiert und anschließend wieder neu kodiert, denn dadurch stimmt der Body, der zur Signaturprüfung genutzt wird, nicht mehr byte-genau mit dem ursprünglich vom Anbieter gesendeten Body überein. Aus diesem Grund sollte ein Webhook-Controller getContent() so früh wie möglich aufrufen, bevor irgendeine andere Middleware oder ein Kernel-Listener Gelegenheit hatte, den Request-Body zu manipulieren, und im Zweifel den betroffenen Endpunkt explizit von generischen Body-Parsing-Listenern ausnehmen.

Ein zweiter häufiger Fehler ist, den Secret-Wert für alle Webhook-Quellen zu teilen, statt pro Anbieter ein eigenes, unabhängiges Secret zu verwenden, was bei einer Kompromittierung eines einzelnen Anbieter-Secrets sofort auch die anderen Endpunkte gefährdet. Ein dritter Fehler ist das Fehlen einer expliziten Timeout- oder Größenbegrenzung für den Webhook-Payload, denn ein Angreifer, der zwar keine gültige Signatur fälschen kann, aber die URL kennt, kann trotzdem versuchen, den Endpunkt mit übergroßen oder besonders langsam gesendeten Requests zu belasten, weshalb eine vernünftige Body-Größenbegrenzung auf Webserver- oder Symfony-Konfigurationsebene sinnvoll bleibt, selbst wenn die Signaturprüfung selbst korrekt implementiert ist.

8. Webhook-Endpunkte automatisiert testen

Ein Webhook-Controller lässt sich hervorragend mit einem WebTestCase testen, indem der Test selbst eine gültige HMAC-Signatur mit demselben Algorithmus und demselben, in der Testumgebung konfigurierten Secret berechnet und als Header mitschickt. So lassen sich sowohl der Erfolgsfall mit einer korrekten Signatur als auch der Fehlerfall mit einer bewusst falschen oder fehlenden Signatur gezielt abdecken, wobei der Fehlerfall explizit den erwarteten 401-Statuscode und die Abwesenheit jeder fachlichen Verarbeitung prüfen sollte.

Für den Idempotenz-Mechanismus lohnt sich ein eigener Test, der denselben Request-Payload und dieselbe Event-ID zweimal hintereinander an den Endpunkt sendet und prüft, dass die fachliche Verarbeitung, etwa ein Datenbank-Insert oder ein versendetes E-Mail, tatsächlich nur einmal stattfindet. Ein solcher Test deckt genau die Race-Condition- und Duplikat-Szenarien ab, die in der Praxis am schwierigsten manuell nachzuvollziehen sind, weil sie von der tatsächlichen Zustellungslogik des externen Anbieters abhängen und sich lokal nur simulieren, nicht aber real reproduzieren lassen.

9. Eine Checkliste für produktionsreife Webhook-Endpunkte

Ein produktionsreifer Webhook-Endpunkt sollte mindestens folgende Punkte erfüllen: einen dedizierten Controller pro Anbieter, außerhalb der regulären Session-basierten Firewall-Konfiguration, eine Signaturprüfung mit hash_hmac() und hash_equals() auf dem unveränderten rohen Body, ein pro Anbieter individuelles Secret aus dem Secrets-Vault statt aus Klartext-Code, eine transaktional mit der fachlichen Verarbeitung verbundene Idempotenz-Prüfung über eine eindeutige Event-ID, und eine angemessene Body-Größenbegrenzung gegen Missbrauch.

Zusätzlich empfiehlt sich strukturiertes Logging jedes eingehenden Webhooks, unabhängig vom Erfolg der Signaturprüfung, damit im Fehlerfall nachvollziehbar bleibt, ob ein Anbieter tatsächlich eine fehlerhafte Signatur gesendet hat oder ob es sich um einen echten Angriffsversuch handelte. Wer diese Punkte von Anfang an berücksichtigt, vermeidet die häufigsten Produktionsprobleme rund um Webhooks, die typischerweise erst auffallen, wenn ein Anbieter unerwartet retryt, ein Secret rotiert wird oder ein Angreifer gezielt versucht, den Endpunkt zu missbrauchen.

10. Zusammenfassung

11. FAQ: Webhook-Empfang und HMAC-Verifikation: Das Wichtigste auf einen Blick