Webhook-Daten vor der Verarbeitung prüfen

Vor jeder weiteren Verarbeitung prüfen Sie drei Dinge: Stammt die Anfrage nach der anbieterspezifischen Signaturprüfung vom erwarteten Absender, passen Ereignistyp und Aktion zum Workflow, und sind die nötigen Werte vorhanden? Erst wenn alle Prüfungen bestanden sind, darf der Webhook eine CRM-Änderung auslösen; ein HTTP-2XX bestätigt zunächst nur den Empfang.

Herkunft prüfen

Bei GitHub steht die Signatur im Header X-Hub-Signature-256. Berechnen Sie mit dem geheimen Token und dem unveränderten Anfrageinhalt den HMAC-Hash als Hex-Digest; er beginnt mit sha256=. Behandeln Sie den Inhalt als UTF-8 und vergleichen Sie die Signaturen mit einem konstantzeitlichen Verfahren, nicht mit ==.

Erzeugen Sie für GitHub ein zufälliges Secret mit hoher Entropie und speichern Sie es sicher: weder im Anwendungscode noch in einem Repository. Verwenden Sie HTTPS und lassen Sie die SSL-Prüfung aktiviert. Eine IP-Allowlist kann eine zusätzliche Schutzschicht sein; die aktuellen GitHub-IP-Adressen liefert GET /meta und die Liste sollte regelmäßig aktualisiert werden.

Für ausgehende HubSpot-Anfragen an OAuth-Apps gelten andere Header und Prüfschritte: X-HubSpot-Signature-v3 und X-HubSpot-Request-Timestamp. Lehnen Sie eine Anfrage ab, wenn der Zeitstempel älter als fünf Minuten ist. Verketten Sie anschließend UTF-8-kodiert requestMethod + requestUri + requestBody + timestamp, berechnen Sie mit dem Application Secret einen HMAC-SHA-256-Hash, kodieren Sie das Ergebnis mit Base64 und vergleichen Sie es konstantzeitlich mit der Signatur.

Die Verfahren von GitHub und HubSpot sind nicht austauschbar. Prüfen Sie die Signatur, bevor Sie Nutzdaten weiterverarbeiten oder eine CRM-Wirkung erlauben.

Ereignis und Inhalt eingrenzen

Prüfen Sie nach erfolgreicher Echtheitsprüfung, ob der Workflow den Ereignistyp und die gemeldete Aktion zulässt. Bei GitHub steht der Ereignistyp im Request-Header X-GitHub-Event, die Aktion im obersten Payload-Feld action. Abonnieren Sie nur die benötigten Ereignistypen und lassen Sie nur die für den Workflow vorgesehenen Kombinationen weiter. GitHub ergänzt Ereignistypen und Aktionen; unbekannte Kombinationen dürfen daher nicht automatisch eine CRM-Änderung auslösen.

Prüfen Sie danach die Werte, die der konkrete Übergabefall benötigt, etwa eine Ereigniskennung, eine Kontaktkennung und einen bekannten Zielwert. Fehlende Pflichtwerte oder unbekannte Auswahlwerte gehören in einen sichtbaren Korrekturfall. Unbekannte Payload-Felder dürfen keine beliebigen CRM-Felder befüllen.

Wiederholte Zustellungen behandeln

Webhooks können erneut zugestellt werden. Speichern Sie eine geeignete Zustellkennung und das Verarbeitungsergebnis, damit dieselbe Zustellung nicht dieselbe CRM-Wirkung erneut auslöst. Prüfen Sie für jeden Anbieter, ob stabile Kennungen und das Wiederholungsverhalten dokumentiert sind.

Berücksichtigen Sie gleichzeitige Verarbeitungsversuche und den Fall, dass die CRM-Änderung erfolgt, das Ergebnis aber nicht gespeichert wird. Prüfen Sie dann zuerst den tatsächlichen Zielzustand, bevor Sie eine weitere CRM-Wirkung zulassen.

GitHub empfiehlt eine HTTP-2XX-Bestätigung innerhalb von zehn Sekunden; bei Bedarf kann die weitere Verarbeitung nachgelagert erfolgen. Die Echtheitsprüfung muss vor der vertrauensvollen Annahme der Daten stattfinden, und Ereignistyp, Aktion sowie Pflichtwerte müssen vor der CRM-Änderung geprüft sein.

Jeden Ausgang sichtbar machen

Eine Fehlermeldung sollte Kennung, Zeitpunkt und Ursache enthalten. Geheimnisse und unnötige Personendaten gehören nicht in allgemeine Benachrichtigungen. Kontrollieren Sie bei der Abnahme sowohl die Eingangsentscheidung als auch den tatsächlichen CRM-Zustand.