Webhooks

PollHero sendet pro Event einen signierten POST-Request mit JSON-Body an die Endpoint-URL deines Projekts. So landen Antworten ohne eigene Abfrage in deinem CRM, deinem Data Warehouse, in Slack oder in einem Automatisierungstool wie Zapier, Make oder n8n. Die übrige Data Export API holt Daten auf Anfrage ab, Webhooks bringen sie dir, sobald sie entstehen.

Webhook einrichtenLink zur Überschrift kopieren

Webhooks richtest du pro Projekt ein. Die Einstellungen können Inhaber des Accounts und Admins des Projekts ändern.

Schritt 1: Öffne die Projekteinstellungen, scrolle zum Abschnitt Webhook und setze den Toggle Webhook aktivieren auf AN.

Schritt 2: Aktiviere eines oder beide Events: Antworten senden (Event question_answered) und Abschluss der Umfrage senden (Event survey_completed). Unter jedem aktiven Event erscheint ein Feld Endpoint-URL. Trag dort die URL deines Empfängers ein. Beide Events können an dieselbe oder an verschiedene URLs gehen.

Schritt 3: Klick neben dem Feld auf Test-Request senden. PollHero schickt einen Beispiel-Request mit "test": true an die eingetragene URL und zeigt dir an, ob dein Endpoint erfolgreich geantwortet hat. Der Test funktioniert schon vor dem Speichern.

Schritt 4: Speichere die Projekteinstellungen. Beim ersten Speichern mit aktivem Event erzeugt PollHero den Verification Token und das Signing Secret. Beide findest du danach im Abschnitt Verifizierung und kannst sie mit Kopieren übernehmen.

Solange Webhook aktivieren auf AUS steht, wird nichts gesendet, auch wenn einzelne Events aktiv sind.

Anforderungen an den EndpointLink zur Überschrift kopieren

• Die URL muss öffentlich über http oder https erreichbar sein. Adressen in privaten Netzen sowie Hostnamen wie localhost lehnt PollHero ab.
• Der Endpoint muss innerhalb von 15 Sekunden mit einem Status 2xx antworten. Für den Verbindungsaufbau gelten 5 Sekunden.
• Weiterleitungen folgt PollHero nicht. Ein Status 301 oder 302 zählt als fehlgeschlagene Zustellung.
• Antworte am besten sofort mit 200 und verarbeite den Inhalt danach im Hintergrund.

EventsLink zur Überschrift kopieren

• Übersprungene Fragen lösen kein Event aus.
• Ändert jemand innerhalb derselben Teilnahme eine Antwort, wird question_answered erneut gesendet, mit neuer messageId.
• survey_completed kommt einmal pro Teilnahme.
• Ist PII Masking aktiv, kommen die Antworten bereits maskiert an.
• Antworten aus dem CSV-Import lösen keine Events aus.
• Die Stimmungsanalyse läuft erst nach dem Versand. Das Sentiment einer Freitextantwort bekommst du über die Data Export API.

Aufbau des RequestsLink zur Überschrift kopieren

HeaderLink zur Überschrift kopieren

Gemeinsame FelderLink zur Überschrift kopieren

Jeder Body beginnt mit denselben Feldern:

Event question_answeredLink zur Überschrift kopieren

{
  "messageId": "0e0938c0-1e85-413b-8ffd-5a0e3a26340a",
  "deliveryTries": 1,
  "event": "question_answered",
  "timestamp": "2026-10-27T11:51:20.000000Z",
  "survey": {
    "id": "21cba834-ad20-4f3b-929d-5abfff8c96ae",
    "name": "Post-Purchase-Umfrage"
  },
  "question": {
    "id": "1165ac0a-1fcf-451a-a361-db75602d1283",
    "body": "Wie wahrscheinlich ist es, dass du uns weiterempfiehlst?",
    "type": "nps"
  },
  "response": {
    "user_id": "23decc90-820a-40bf-92ea-db493c71bfa0",
    "collected_at": "2026-10-27T11:51:19.000000Z",
    "completed": false,
    "url": "https://shop.example.com/checkout/thank-you",
    "order_id": "1232"
  },
  "answer": {
    "answer": { "content": 9, "tag": "promoter" }
  },
  "respondent": {
    "id": "23decc90-820a-40bf-92ea-db493c71bfa0",
    "attributes": {
      "email": "jane@example.com",
      "customer_type": "returning",
      "total_purchases": 3,
      "plan": "pro"
    }
  }
}

Event survey_completedLink zur Überschrift kopieren

{
  "messageId": "7c1d2a9e-5b7f-4d0e-9a3c-1f2e3d4c5b6a",
  "deliveryTries": 1,
  "event": "survey_completed",
  "timestamp": "2026-10-27T11:52:01.000000Z",
  "survey": {
    "id": "21cba834-ad20-4f3b-929d-5abfff8c96ae",
    "name": "Post-Purchase-Umfrage"
  },
  "response": {
    "user_id": "23decc90-820a-40bf-92ea-db493c71bfa0",
    "collected_at": "2026-10-27T11:51:19.000000Z",
    "completed": true,
    "url": "https://shop.example.com/checkout/thank-you",
    "order_id": "1232",
    "completed_at": "2026-10-27T11:52:01.000000Z",
    "time_taken": 42,
    "device_type": "Desktop",
    "browser": "Chrome",
    "country": "Germany",
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "autumn",
      "term": null,
      "content": null
    }
  },
  "answers": [
    {
      "question_id": "1165ac0a-1fcf-451a-a361-db75602d1283",
      "question_type": "nps",
      "question_body": "Wie wahrscheinlich ist es, dass du uns weiterempfiehlst?",
      "answer": { "content": 9, "tag": "promoter" }
    },
    {
      "question_id": "8d2f6b1c-3a4e-4f5d-9c7b-2e1f0a9b8c7d",
      "question_type": "text",
      "question_body": "Was ist der Grund für deine Bewertung?",
      "answer": "Schnelle Lieferung, gerne wieder."
    }
  ],
  "respondent": {
    "id": "23decc90-820a-40bf-92ea-db493c71bfa0",
    "attributes": {
      "email": "jane@example.com",
      "customer_type": "returning",
      "total_purchases": 3,
      "plan": "pro"
    }
  }
}

answers enthält alle beantworteten Fragen in der Reihenfolge, in der sie beantwortet wurden. Jeder Eintrag trägt zusätzlich question_id, question_type und question_body.

Objekt responseLink zur Überschrift kopieren

Nur bei survey_completed:

Objekt respondentLink zur Überschrift kopieren

Anders als in der Data Export API bekommst du hier immer alle Attribute, ohne sie anzufordern, und als Objekt mit den Attributnamen als Schlüssel.

Signatur prüfenLink zur Überschrift kopieren

Jeder Request trägt zwei Merkmale, an denen dein Endpoint erkennt, dass er wirklich von PollHero kommt:

• X-PollHero-Token enthält den Verification Token des Projekts. Vergleiche ihn mit dem Wert aus den Projekteinstellungen.
• X-PollHero-Signature enthält den HMAC-SHA256 des unveränderten Request-Bodys, berechnet mit dem Signing Secret, als Hexadezimalzahl in Kleinbuchstaben.

Berechne die Signatur über die rohen Bytes des Bodys, bevor du das JSON parst. Ein neu serialisiertes JSON ergibt eine andere Signatur. Vergleiche mit einer zeitkonstanten Funktion.

// Node.js mit Express: den rohen Body behalten
import crypto from "node:crypto";
import express from "express";

const app = express();
app.post("/pollhero-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto
    .createHmac("sha256", process.env.POLLHERO_SIGNING_SECRET)
    .update(req.body)
    .digest("hex");
  const given = req.get("X-PollHero-Signature") ?? "";

  if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const payload = JSON.parse(req.body);
  // Verarbeitung im Hintergrund anstoßen ...
  res.sendStatus(200);
});

<?php
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, getenv('POLLHERO_SIGNING_SECRET'));
$given = $_SERVER['HTTP_X_POLLHERO_SIGNATURE'] ?? '';

if (! hash_equals($expected, $given)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($body, true);
http_response_code(200);

Mit Neu generieren im Abschnitt Verifizierung erzeugst du neuen Token und neues Secret. Die alten Werte gelten ab diesem Moment nicht mehr, dein Empfänger muss die neuen Werte sofort bekommen.

Zustellung und WiederholungenLink zur Überschrift kopieren

• Eine Zustellung gilt als erfolgreich, wenn dein Endpoint mit Status 2xx antwortet. Jeder andere Status, ein Timeout oder ein Verbindungsfehler zählt als Fehlschlag.
• Nach einem Fehlschlag versucht PollHero es bis zu vier weitere Male: nach 1, 5, 15 und 60 Minuten. deliveryTries zählt die Versuche, messageId bleibt gleich. Danach wird die Nachricht verworfen.
• Die Reihenfolge ist nicht garantiert. Zwei Antworten können in anderer Reihenfolge ankommen, als sie gegeben wurden. Nutze timestamp oder collected_at, wenn die Reihenfolge wichtig ist.
• Webhooks laufen asynchron. In der Regel kommt der Request wenige Sekunden nach der Antwort an.

Tipps für den EmpfängerLink zur Überschrift kopieren

• Beantworte jeden Request sofort mit 200 und verarbeite die Daten anschließend. So vermeidest du Timeouts und Wiederholungen.
• Speichere messageId und ignoriere Nachrichten, die du schon kennst. Bei Wiederholungen kann dieselbe Nachricht mehr als einmal ankommen.
• Für die vollständige Historie oder einen Abgleich nutze die Data Export API. Webhooks liefern nur Ereignisse ab dem Zeitpunkt der Aktivierung.