- Um eine Anfrage mit der neuesten Version der HubSpot-Signatur zu validieren, verwenden Sie den
X-HubSpot-Signature-V3-Header und folgen Sie den zugehörigen Anweisungen zum Validieren der v3-Version der Signatur . - Aus Gründen der Abwärtskompatibilität enthalten Anfragen von HubSpot auch ältere Versionen der Signatur. Um eine ältere Version der Signatur zu validieren, überprüfen Sie den
X-HubSpot-Signature-Version-Header und befolgen Sie dann die folgenden Anweisungen, je nachdem, ob die Versionv1oderv2ist.
Anfragen mit der v1-Anfrageignatur validieren
Wenn Ihre App CRM-Objekt-Events über die Webhooks-API abonniert hat, werden Anfragen von HubSpot mit demX-HubSpot-Signature-Version-Header auf v1 festgelegt gesendet. Der X-HubSpot-Signature-Header ist ein SHA-256-Hash, der mithilfe des Client-Geheimnisses Ihrer App in Kombination mit den Details der Anfrage erstellt wurde.
Um diese Version der Signatur zu überprüfen, führen Sie die folgenden Schritte aus:
- Erstellen Sie eine Zeichenfolge, die Folgendes miteinander verkettet:
Client secret+request body(falls vorhanden). - Erstellen Sie einen SHA-256-Hash von der resultierenden Zeichenfolge.
- Vergleichen Sie den Hash-Wert mit dem Wert des
X-HubSpot-Signature-Headers:- Wenn sie gleich sind, hat diese Anfrage die Überprüfung bestanden.
- Wenn diese Werte nicht übereinstimmen, wurde diese Anfrage möglicherweise während des Transfers manipuliert, oder jemand spooft Anfragen an Ihren Endpunkt.
Beispiele für v1-Anfragesignaturen
Beispiel für Python
Beispiel für Ruby
Beispiel für Node.js
Beispiel für Java
232db2615f3d666fe21a8ec971ac7b5402d33b9a925784df3ca654d05f4817de
Anfragen mit der v2-Anfragesignatur validieren
Wenn Ihre App Daten aus einer Webhook-Aktion in einem Workflow verarbeitet oder wenn Sie Daten für eine benutzerdefinierte CRM-Karte zurückgeben, wird die Anfrage von HubSpot mit demX-HubSpot-Signature-Version-Header auf v2 festgelegt gesendet. Der X-HubSpot-Signature-Header ist ein SHA-256-Hash, der mithilfe des Client-Geheimnisses Ihrer App in Kombination mit den Details der Anfrage erstellt wurde.
Um diese Signatur zu überprüfen, führen Sie die folgenden Schritte aus:
- Erstellen Sie eine Zeichenfolge, die Folgendes miteinander verkettet:
Client secret+http method+URI+request body(falls vorhanden). - Erstellen Sie einen SHA-256-Hash von der resultierenden Zeichenfolge.
- Vergleichen Sie den Hash-Wert mit der Signatur.
- Wenn sie gleich sind, hat diese Anfrage die Überprüfung bestanden.
- Wenn diese Werte nicht übereinstimmen, wurde diese Anfrage möglicherweise während des Transfers manipuliert, oder jemand spooft Anfragen an Ihren Endpunkt.
- Der zur Erstellung der Quellzeichenfolge verwendete URI muss genau mit der ursprünglichen Anfrage übereinstimmen, einschließlich des Protokolls. Wenn Sie Schwierigkeiten bei der Validierung der Signatur haben, stellen Sie sicher, dass alle Abfrageparameter in genau der gleichen Reihenfolge sind wie in der ursprünglichen Anfrage aufgeführt.
- Die Quellzeichenfolge sollte vor der Berechnung des SHA-256-Hash-Werts UTF-8-codiert werden.
Beispiel für eine GET-Anfrage
Für eineGET-Anfrage benötigen Sie das Client-Geheimnis Ihrer App und bestimmte Felder aus den Metadaten Ihrer Anfrage. Diese Felder sind unten mit Platzhalterwerten aufgeführt:
- Client-Geheimnis:
yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy - HTTP-Methode:
GET - URI:
https://www.example.com/webhook_uri - Anfragetext:
""
yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyyGEThttps://www.example.com/webhook_uri
Nach der Berechnung eines SHA-256-Hashes der obigen verketteten Zeichenfolge würde die resultierende Signatur, die mit der im Header übereinstimmen sollte, wie folgt aussehen: eee2dddcc73c94d699f5e395f4b9d454a069a6855fbfa152e91e88823087200e
Beispiel für eine POST-Anfrage
Für einePOST-Anfrage benötigen Sie das Client-Geheimnis Ihrer App, bestimmte Felder aus den Metadaten Ihrer Anfrage und eine Zeichenfolgendarstellung des Anfragetextes (z. B. die Verwendung von JSON.stringify(request.body) für einen Node.js-Dienst). Diese Felder sind unten mit Platzhalterwerten aufgeführt:
- Client-Geheimnis:
yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy - HTTP-Methode:
POST - URI:
https://www.example.com/webhook_uri - Anfragetext:
{"example_field":"example_value"}
yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyyPOSThttps://www.example.com/webhook_uri{"example_field":"example_value"}
Nach der Berechnung eines SHA-256-Hashes der obigen verketteten Zeichenfolge würde die resultierende Signatur, die mit der im Header übereinstimmen sollte, wie folgt aussehen:9569219f8ba981ffa6f6f16aa0f48637d35d728c7e4d93d0d52efaa512af7900
Nach dem \[SHA-ing]] der Signatur können Sie die resultierende erwartete Signatur mit der im x-hubspot-signature-Header der Anfrage angegebenen Signatur vergleichen:
Im folgenden Snippet wird beschrieben, wie Sie eine v2-Anfragevalidierung für eine GET-Anfrage integrieren können, wenn Sie einen Express-Server ausführen, um eingehende Anfragen zu verarbeiten. Beachten Sie, dass der folgende Code-Block ein Beispiel ist und bestimmte Abhängigkeiten auslässt, die Sie möglicherweise benötigen, um einen voll funktionsfähigen Express-Dienst auszuführen. Vergewissern Sie sich, dass Sie die neuesten stabilen und sicheren Bibliotheken ausführen, wenn Sie die Anfragevalidierung für Ihren spezifischen Dienst implementieren.
Beispiele für v2-Anfragesignaturen
Beispiel für Node.js
Beispiel für Java
v3-Anfragesignaturen validieren
DerX-HubSpot-Signature-v3-Header ist ein HMAC SHA-256-Hash, der mit dem Client-Geheimnis Ihrer App in Kombination mit Details der Anfrage erstellt wird. Sie enthält auch einen X-HubSpot-Request-Timestamp-Header.
Wenn Sie eine Anfrage mit dem X-HubSpot-Signatur-v3-Header validieren, müssen Sie:
- Die Anfrage ablehnen, wenn der Zeitstempel älter als 5 Minuten ist.
- Im Anfrage-URI eines der URL-codierten Zeichen, die in der folgenden Tabelle aufgeführt sind. Sie müssen das Fragezeichen, das den Anfang der Abfragezeichenfolge angibt, nicht decodieren.
| Codierter Wert | Decodierter Wert |
|---|---|
%3A | : |
%2F | / |
%3F | ? |
%40 | @ |
%21 | ! |
%24 | $ |
%27 | ' |
%28 | ( |
%29 | ) |
%2A | * |
%2C | , |
%3B | ; |
- Erstellen Sie eine Zeichenfolge, die Folgendes miteinander verkettet:
requestMethod+requestUri+requestBody+ Zeitstempel (falls vorhanden). Der Zeitstempel wird vomX-HubSpot-Request-Timestamp-Header bereitgestellt. - Erstellen Sie einen HMAC SHA-256-Hash der resultierenden Zeichenfolge, indem Sie das Anwendungsgeheimnis als das Geheimnis für die HMAC SHA-256-Funktion verwenden.
- Base64-Codieren Sie das Ergebnis der HMAC-Funktion.
- Vergleichen Sie den Hash-Wert mit der Signatur. Wenn sie gleich sind, wurde diese Anfrage als von HubSpot stammend verifiziert. Es wird empfohlen, einen Zeichenfolgenvergleich mit Zeitkonstant zu verwenden, um sich vor Rechenzeitangriffen zu schützen.
POST-Anfrage integrieren können, wenn Sie einen Backend-Service verwenden, um eingehende Anfragen zu verarbeiten. Beachten Sie, dass die folgenden Code-Blocks bestimmte Abhängigkeiten auslassen, die Sie möglicherweise benötigen, um einen voll funktionsfähigen Backend-Dienst auszuführen. Vergewissern Sie sich, dass Sie die neuesten stabilen und sicheren Bibliotheken ausführen, wenn Sie die Anfragevalidierung für Ihren spezifischen Dienst implementieren.