Anfragen von HubSpot validieren

Um sicherzustellen, dass die Anfragen, die Ihre Integration von HubSpot erhält, tatsächlich von HubSpot stammen, werden mehrere Header in der Anfrage ausgefüllt. Sie können diese Header zusammen mit Feldern der eingehenden Anfrage verwenden, um die Signatur der Anfrage zu überprüfen.

Die zur Überprüfung der Signatur verwendete Methode hängt von der Version der Signatur ab.

  • Um eine Anfrage mit der neuesten Version der HubSpot-Signatur zu validieren, verwenden Sie den X-HubSpot-Signatur-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-Signatur-Version-Header und befolgen Sie dann die folgenden Anweisungen, je nachdem, ob die Version v1 oder v2 ist.

In den folgenden Anweisungen erfahren Sie, wie Sie einen Hash-Wert aus dem Client-Geheimnis Ihrer App und den Feldern einer eingehenden Anfrage ableiten. Nachdem Sie den Hash-Wert berechnet haben, vergleichen Sie ihn mit der Signatur. Wenn beide gleich sind, hat die Anfrage die Validierung bestanden. Andernfalls wurde die Anfrage möglicherweise während des Transfers manipuliert, oder jemand spooft Anfragen an Ihren Endpunkt.

Anfragen mit der v1-Anfrageignatur validieren

Wenn Ihre App CRM-Objekt-Events über die Webhooks-API abonniert hat, werden Anfragen von HubSpot mit dem X-HubSpot-Signatur-Version-Header auf v1 festgelegt gesendet. Der X-HubSpot-Signatur-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-Geheimnis + Anfragetext (falls vorhanden)
  • Erstellen Sie einen SHA-256-Hash von der resultierenden Zeichenfolge.
  • Vergleichen Sie den Hash-Wert mit dem Wert des X-HubSpot-Signatur-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.

Beispiel für eine Anfrage mit einem Text:

//Client secret : yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy // Request body: [ {"eventId":1,"subscriptionId":12345," portalId":62515", occurredAt":1564113600000", subscriptionType":"contact.creation", "attemptNumber":0, "objectId":123, "changeSource":"CRM", "changeFlag":"NEW", "appId":54321} ]

Beispiele für die v1-Anfragesignatur: 

NOTE: This is only an example for generating the expected hash. You will need to compare this expected hash with the actual hash in the X-HubSpot-Signature header. >>> import hashlib >>> client_secret = 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy' >>> request_body = '[{"eventId":1,"subscriptionId":12345,"portalId":62515,"occurredAt":1564113600000,"subscriptionType":"contact.creation","attemptNumber":0,"objectId":123,"changeSource":"CRM","changeFlag":"NEW","appId":54321}]' >>> source_string = client_secret + request_body >>> source_string 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy[{"eventId":1,"subscriptionId":12345,"portalId":62515,"occurredAt":1564113600000,"subscriptionType":"contact.creation","attemptNumber":0,"objectId":123,"changeSource":"CRM","changeFlag":"NEW","appId":54321}]' >>> hashlib.sha256(source_string).hexdigest() '232db2615f3d666fe21a8ec971ac7b5402d33b9a925784df3ca654d05f4817de' NOTE: This is only an example for generating the expected hash. You will need to compare this expected hash with the actual hash in the X-HubSpot-Signature header. irb(main):003:0> require 'digest' => true irb(main):004:0> client_secret = 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy' => "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" irb(main):005:0> request_body = '[{"eventId":1,"subscriptionId":12345,"portalId":62515,"occurredAt":1564113600000,"subscriptionType":"contact.creation","attemptNumber":0,"objectId":123,"changeSource":"CRM","changeFlag":"NEW","appId":54321}]' => "[{\"eventId\":1,\"subscriptionId\":12345,\"portalId\":62515,\"occurredAt\":1564113600000,\"subscriptionType\":\"contact.creation\",\"attemptNumber\":0,\"objectId\":123,\"changeSource\":\"CRM\",\"changeFlag\":\"NEW\",\"appId\":54321}]" irb(main):006:0> source_string = client_secret + request_body => "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy[{\"eventId\":1,\"subscriptionId\":12345,\"portalId\":62515,\"occurredAt\":1564113600000,\"subscriptionType\":\"contact.creation\",\"attemptNumber\":0,\"objectId\":123,\"changeSource\":\"CRM\",\"changeFlag\":\"NEW\",\"appId\":54321}]" irb(main):007:0> Digest::SHA256.hexdigest source_string => "232db2615f3d666fe21a8ec971ac7b5402d33b9a925784df3ca654d05f4817de" NOTE: This is only an example for generating the expected hash. You will need to compare this expected hash with the actual hash in the X-HubSpot-Signature header. > const crypto = require('crypto') undefined > client_secret = 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy' 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy' > request_body = '[{"eventId":1,"subscriptionId":12345,"portalId":62515,"occurredAt":1564113600000,"subscriptionType":"contact.creation","attemptNumber":0,"objectId":123,"changeSource":"CRM","changeFlag":"NEW","appId":54321}]' '[{"eventId":1,"subscriptionId":12345,"portalId":62515,"occurredAt":1564113600000,"subscriptionType":"contact.creation","attemptNumber":0,"objectId":123,"changeSource":"CRM","changeFlag":"NEW","appId":54321}]' > source_string = client_secret + request_body 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy[{"eventId":1,"subscriptionId":12345,"portalId":62515,"occurredAt":1564113600000,"subscriptionType":"contact.creation","attemptNumber":0,"objectId":123,"changeSource":"CRM","changeFlag":"NEW","appId":54321}]' > hash = crypto.createHash('sha256').update(source_string).digest('hex') '232db2615f3d666fe21a8ec971ac7b5402d33b9a925784df3ca654d05f4817de'

Der resultierende Hash würde folgendermaßen aussehen:
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 dem X-HubSpot-Signatur-Version-Header auf v2 festgelegt gesendet. Der X-HubSpot-Signatur-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-Geheimnis + HTTP-Methode + URI + Anfragetext (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.

Hinweise:
  • 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:


Beispiel für eine Anfrage mit einem Text:

 

Die v3-Anfragesignatur validieren

Der X-HubSpot-Signatur-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-Anfragezeitstempel-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 UTF-8-codierte Zeichenfolge, die Folgendes miteinander verkettet: requestMethod + requestUri + requestBody + Zeitstempel. Der Zeitstempel wird vom X-HubSpot-Anfragezeitstempel-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.
War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.