Beiträge in diesem Abschnitt

Webhooks-Referenz

Verfügbar auf Scale plan label.

Ü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:

  1. Sie richten einen Webhook ein, normalerweise auf Ihrem eigenen Server/Website, mit einer eindeutigen URL.
  2. 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).
  3. Hotjar sendet dann HTTP POST-Anfragen an Ihre Webhook-URL, sobald eine neue Umfrage oder Feedback-Antwort erstellt wird.

Zurück zum Anfang

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.

Zurück zum Anfang

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 dies Umfrage_Antwort, feedback_response oder test_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.

Zurück zum Anfang

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.

Zurück zum Anfang

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.

Zurück zum Anfang

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 sein Reaktion, Langtext, Kurztext, Einzeloption, Mehrfachauswahl, E-Mail, 1-5-Bewertung, 1-7-Bewertung, nps oder unbekannt.
    • 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.

Zurück zum Anfang

Verwandte Beiträge