Überblick
Mit Hotjar Webhooks können Sie benachrichtigt werden, wenn ein Ereignis eintritt, z. B. wenn ein Besucher Ihrer Website eine neue Umfragebeantwortung abgibt. Sie richten einen "Webhook" (eine URL) auf Ihrer eigenen Website oder auf der Website eines Partnerunternehmens ein, teilen diesen Webhook mit Hotjar und erhalten dann Ereignis-Payloads, wenn Ereignisse eintreten. Webhooks sind also eine Möglichkeit, Daten in Echtzeit an Ihre Systeme zu übermitteln.
Technisch ausgedrückt:
- Sie richten einen Webhook ein, normalerweise auf Ihrem eigenen Server/Website, mit einer eindeutigen URL.
- Innerhalb der Hotjar-Benutzeroberfläche geben Sie die Webhook-URL in ein Umfrage- oder Feedback-Widget ein (indem Sie das Umfrage- oder Feedback-Widget bearbeiten).
- Hotjar sendet dann HTTP POST-Anfragen an Ihre Webhook-URL, sobald eine neue Umfrage oder Feedback-Antwort erstellt wird.
Warum Webhooks verwenden?
Webhooks ergänzen die Hotjar-API für Umfrageantworten. Während die API vor allem für den Massenexport (Herunterladen) nützlich ist, sind Webhooks für den sofortigen Empfang von Umfrage- und Feedbackantworten nützlich, sobald sie erstellt werden. Sie sollten die Verwendung von Webhooks in Betracht ziehen, wenn:
- Sie sofort Daten erhalten möchten.
- Sie Daten an Ihre Systeme, z. B. ein Data Warehouse, senden möchten, ohne unsere API abfragen zu müssen.
- Ein Partner bietet eine Integration mit Hotjar über Webhooks an.
Wie Webhooks funktionieren
Wenn ein Ereignis eintritt, sendet Hotjar eine Nachricht an jeden konfigurierten Webhook:
- Die Nachricht wird als HTTP POST-Anfrage an Ihren Webhook gesendet.
- Die Anfrage wird als UTF-8 kodiert.
- Der Inhaltstyp ist
anwendung/json
. - Der Körper der Anfrage ist daher ein JSON-Objekt mit den folgenden Eigenschaften:
-
Ereignis
- Zeichenkette. Der Wert dieser Eigenschaft ist der Name des Ereignisses. Zum Zeitpunkt der Erstellung ist diesUmfrage_Antwort
,feedback_response
odertest_message
. -
Version
- Ganzzahl. Diese Eigenschaft ist für die zukünftige Verwendung reserviert, derzeit wird sie immer auf die Zahl 1 gesetzt. -
Daten
- Der Wert dieser Eigenschaft ist ein JSON-Objekt mit den Daten des Ereignisses. Die Felder des Objekts sind für jedes Ereignis spezifisch (siehe unten).
-
Wir senden Ereignisse so schnell wie möglich nach ihrem Auftreten; in der Praxis sollten Sie eine Nachricht innerhalb weniger Sekunden erhalten. In seltenen Fällen können sich Nachrichten verzögern, aber jedes Ereignis enthält das Datum und die Uhrzeit, zu der es eingetreten ist, so dass wir empfehlen, dieses Datum zu verwenden, anstatt das Datum und die Uhrzeit, zu der Ihr Webhook eine Nachricht erhält.
Hotjar garantiert nicht, dass die Reihenfolge der empfangenen Nachrichten mit der Reihenfolge des Auftretens der Ereignisse übereinstimmt. Einige Ereignisse enthalten einen Index-Parameter
, der für die Reihenfolge verwendet werden kann.
Webhook-Anforderungen
Ihr Webhook muss die folgenden Anforderungen erfüllen:
- Der Webhook muss HTTPS (TLS) sein.
- Der Server muss innerhalb von 10 Sekunden antworten.
- Der Server muss mit einem beliebigen HTTP-2XX-Statuscode antworten (jeder HTTP-Statuscode zwischen 200 und 299).
- Der Server muss jeden unerwarteten Ereignistyp akzeptieren, ohne einen Fehler zurückzugeben.
- Der Server sollte versehentlich doppelte Nachrichten verarbeiten. Obwohl Hotjar alles daran setzt, eine Nachricht nur einmal an Ihren Webhook zu senden, können wir dies nicht garantieren. Ihr Webhook sollte sich daher auf den eindeutigen Identifikator in der Nachricht verlassen, um eine Deduplizierung zu ermöglichen.
Wiederholungen
Hotjar wird versuchen, das Senden eines Webhooks im Falle eines Fehlers zu wiederholen. Hotjar versucht dies bis zu sechs Mal, wobei zwischen den Versuchen eine Pause eingelegt wird:
Wiederholungsversuch | Verzögerung vor dem erneuten Versuch |
1 | 30 Sekunden |
2 | 1 Minute |
3 | 2 Minuten |
4 | 5 Minuten |
5 | 10 Minuten |
6 | 20 Minuten |
Hotjar wird den Sendevorgang so lange wiederholen, bis eine der folgenden Bedingungen eintritt:
- Der Webhook antwortet mit einem 2XX-Statuscode (d. h. eine erfolgreiche Antwort).
- Der Webhook antwortet mit einem 410-Statuscode (woraufhin Hotjar den Webhook aus Ihrer Umfrage oder Ihrem Feedback-Widget löscht).
- Maximal 6 Wiederholungsversuche sind möglich.
Nutzdaten
Hotjar kann in Zukunft weitere Felder zu diesen Payloads hinzufügen, so dass Ihr Webhook keinen Fehler auslösen sollte, wenn ein Feld vorhanden ist, das Sie nicht erwartet haben. Beachten Sie, dass jedes Feld zusätzlich zu dem angegebenen Typ auf Null gesetzt werden kann.
Feedback-Antwort
Name des Ereignisses: feedback_response
-
id
Ganzzahl - Die eindeutige Kennung der Rückmeldung. -
index
Ganzzahl - Der Index dieser Feedback-Antwort innerhalb des Feedback-Widgets. -
feedback_antwort_url
string - Der Link zur Anzeige der Antwort innerhalb der Hotjar-App. -
Nachricht
string - Die Nachricht, die der Benutzer eingegeben hat. -
email
string - Die E-Mail-Adresse, die der Benutzer eingegeben hat, falls vorhanden. -
Gefühl
Integer - Die Emotion/Reaktionsbewertung (1 bis 5), die der Benutzer ausgewählt hat. -
erstellt_str
string - Datum und Uhrzeit der Erstellung der Feedback-Antwort als ISO 8601-String. -
created_timestamp
integer - Datum und Uhrzeit der Erstellung der Feedback-Antwort in Form eines UNIX-Zeitstempels. -
Frage
string - Die Frage im Feedback-Widget, die der Benutzer beantwortet hat. -
site_id
Ganzzahl - Der eindeutige Bezeichner der Hotjar-Site. -
feedback_id
integer - Der eindeutige Bezeichner des Feedback-Widgets. -
feedback_name
string - Der Name des Feedback-Widgets. -
feedback_url
string - Der Link zur Anzeige des Feedback-Widgets innerhalb der Hotjar-App. -
browser
string - Der Name des Browsertyps, der für die Übermittlung der Feedback-Antwort verwendet wird. -
Gerät
string - Der Gerätetyp, der für die Übermittlung der Feedback-Antwort verwendet wird. Es handelt sich um "Tablet", "Mobile" oder "Desktop". -
os
string - Der Name des Betriebssystems, das für die Übermittlung der Feedback-Antwort verwendet wird. -
land_name
string - Das Land, aus dem die Feedback-Antwort erstellt wurde. -
land_code
string - Der Ländercode, aus dem die Feedback-Antwort erstellt wurde. Eine Liste dieser Codes finden Sie in den ISO-3166-Ländercodes. -
window_width
integer - Die Breite des Benutzerfensters beim Absenden der Feedback-Antwort. -
window_height
Integer - Die Höhe des Benutzerfensters bei der Übermittlung der Feedback-Antwort. -
hotjar_user_id
string - Die Hotjar-Benutzer-ID für den Benutzer, der die Feedback-Antwort übermittelt hat (eine UUID).
Umfrage-Antwort
Name des Ereignisses: survey_response
-
id
Ganzzahl - Die eindeutige Kennung der Umfragebeantwortung. -
index
Ganzzahl - Der Index dieser Umfragebeantwortung innerhalb der Umfrage. -
api_id
string - Die öffentliche ID (einschließlich UUID), die sich auf diese Umfragebeantwortung bezieht. -
antwort_url
string - Der Link zum Anzeigen der Antwort innerhalb der Hotjar-App. -
site_id
Ganzzahl - Die eindeutige Kennung der Hotjar-Site. -
umfrage_id
integer - Der eindeutige Bezeichner der Umfrage. -
umfrage_name
string - Der Name der Umfrage. -
umfrage_url
string - Der Link zum Anzeigen der Umfrage innerhalb der Hotjar-App. -
Gerät
string - Der Gerätetyp, der für die Übermittlung der Umfragebeantwortung verwendet wird. Es wird "Tablet", "Mobile" oder "Desktop" sein. -
Browser
string - Der Name des Browsertyps, der für die Übermittlung der Umfragebeantwortung verwendet wird. -
os
string - Der Name des Betriebssystems, das für die Übermittlung der Umfragebeantwortung verwendet wurde. -
land_code
string - Der Ländercode, mit dem die Umfragebeantwortung erstellt wurde. Eine Liste dieser Codes finden Sie in den ISO-3166-Ländercodes. -
land_name
string - Das Land, in dem die Umfragebeantwortung erstellt wurde. -
hotjar_benutzer_id
string - Die Hotjar-Benutzer-ID für den Benutzer, der die Umfragebeantwortung eingereicht hat (eine UUID). -
erstellt_str
string - Datum und Uhrzeit der Erstellung der Umfragebeantwortung als ISO 8601-String. -
created_timestamp
integer - Datum und Uhrzeit der Erstellung der Umfragebeantwortung in Form eines UNIX-Zeitstempels. -
is_complete
boolesch - Kennzeichen, das angibt, ob die Umfragebeantwortung abgeschlossen ist oder nicht. -
aufnahme_url
string - Der Link zu der Hotjar-Aufzeichnung, die diese Umfragebeantwortung enthält, falls vorhanden. -
response_origin_url
string - Die URL der Website, auf der der Benutzer die Umfragebeantwortung eingereicht hat. -
window_width
integer - Die Breite des Benutzerfensters bei der Übermittlung der Umfragebeantwortung. -
window_height
Integer - Die Höhe des Benutzerfensters bei der Übermittlung der Umfragebeantwortung. -
benutzer_attribute
object - Die Attribute des Benutzers, wie sie von der Hotjar Identify API bereitgestellt werden. Jeder Schlüssel und jeder Wert im Objekt repräsentiert das Folgende:-
Schlüssel
string - Der Name des Benutzerattributs. -
Wert
string/integer/float/boolean/datetime - Der Wert des Benutzerattributs.
-
-
Fragen
array/list - Die Fragen und Antworten der Umfrage. Jedes Element hat die folgenden Felder:-
question_id
Ganzzahl - Die eindeutige ID der Frage. -
frage_text
string - Der Text der Frage. -
question_type - Typ der Frage
string - Der Typ der Frage. Dies wird einer der folgenden seinReaktion
,Langtext
,Kurztext
,Einzeloption
,Mehrfachauswahl
,E-Mail
,1-5-Bewertung
,1-7-Bewertung
,nps
oderunbekannt
. -
Antworten
array/list - Die Antworten auf die Frage. Jede Antwort hat die folgenden Felder:-
Antwort
string - Die Antwort, die der Benutzer gegeben hat. -
Kommentar
string - Der Kommentar, den der Benutzer hinterlassen hat (falls vorhanden).
-
-
Bitte beachten Sie, dass Fragen, die der Benutzer nicht beantwortet hat, nicht in der Nutzlast enthalten sind.
Testnachricht
Name des Ereignisses: test_message
Dieses Ereignis wird gesendet, wenn die Hotjar App verwendet wird, um eine Testnachricht an den Webhook zu senden.
Beispiel:
string - Wird immer auf die Zeichenkette "data" gesetzt.
Herabstufung der Website
Ereignis-Name: site_downgrade
Dieses Ereignis wird gesendet, wenn der abonnierte Plan der Hotjar-Site herabgestuft wird und keine Nachrichten mehr an Webhooks senden kann. Bis die Site wieder hochgestuft wird, werden keine weiteren Nachrichten gesendet.
site_id
integer - Die eindeutige ID der Site, die herabgestuft wurde.