Zum Inhalt springen
polzyHilfeZu Polzy

Antworten per Webhook an Ihren Endpunkt senden

Senden Sie jede Antwort, die eine Kampagne erhält, signiert an eine eigene HTTPS-Adresse, oder beliebige Nutzdaten per Workflow-Schritt. So unterscheidet sich der Webhooks-Connector von Einstellungen → API → Webhooks.

Polzy-Team7 Min. LesezeitAktualisiert am 31. Okt. 2026Ab Business
Auf dieser Seite
  1. 1Welchen Webhook brauchen Sie?
  2. 2Bevor Sie beginnen
  3. 3Den Webhooks-Connector verbinden
  4. 4Einer Kampagne ihren Endpunkt geben
  5. 5Was Ihr Endpunkt empfängt
  6. 6Die Signatur prüfen
  7. 7Einen Webhook aus einem Workflow senden
  8. 8Prüfen, ob es funktioniert
  9. 9Fehlerbehebung
  10. 10Gut zu wissen

Der Connector Webhooks sendet jede Antwort, die eine Kampagne erhält, wenige Augenblicke später als signierten POST an eine Adresse auf Ihrem eigenen Server. Auch ein Workflow kann ihn nutzen, um alles zu senden, was der Lauf weiß. Am Ende dieser Anleitung haben Sie einen Endpunkt, der Antworten empfängt, und die Mittel, um zu prüfen, dass jede Anfrage wirklich von Polzy kommt.

Der Webhooks-Connector ist im Tarif Business enthalten. Nur ein Admin kann ihn verbinden und festlegen, wohin die Antworten einer Kampagne gehen.

Welchen Webhook brauchen Sie?

Polzy kann Ihren Server auf drei Arten aufrufen:

Webhooks-Connector (dieser Artikel)Einstellungen → API → WebhooksSchritt Ausgehender Webhook
Was gesendet wirdJede Antwort einer Kampagne, oder die Nutzdaten eines Workflow-SchrittsEreignisse im Arbeitsbereich: eine Antwort angelegt, eine Kampagne beendet, eine Aktion angelegt oder abgeschlossenWas der Workflow-Schritt festlegt
Wo es eingestellt wirdIntegrationen, dann der Tab Integrationen einer Kampagne oder ein Workflow-SchrittEinstellungen → API → WebhooksEin Workflow
TarifBusinessTeamTeam
SigniertX-Polzy-Signature, über den BodyX-Polzy-Signature, über Zeitstempel und BodyNein
Wenn die Zustellung fehlschlägtInsgesamt drei VersucheSechs Versuche in etwa einer halben Stunde, mit einem Protokoll jedes VersuchsDie Fehlerregel des Schritts entscheidet

Für Ereignisse im ganzen Arbeitsbereich siehe Webhooks senden und empfangen.

Bevor Sie beginnen

Sie brauchen:

  • Einen Arbeitsbereich im Tarif Business und darin die Rolle Admin.
  • Integrationen für den Arbeitsbereich eingeschaltet, unter Einstellungen → Allgemein → Was dieser Arbeitsbereich leistet.
  • Einen Endpunkt im Internet, per HTTPS, der einen POST mit JSON-Body annimmt und innerhalb von 10 Sekunden mit einem 2xx-Status antwortet. Polzy lehnt http://-Adressen und Adressen in einem privaten Netzwerk ab.

Den Webhooks-Connector verbinden

Beim Verbinden speichern Sie, was alle Anfragen gemeinsam haben: das Signaturgeheimnis und etwaige Header.

  1. Öffnen Sie in der Seitenleiste unter Automatisieren die Seite Integrationen und wählen Sie den Tab Verfügbar.
  2. Suchen Sie Webhooks und wählen Sie Verbinden.
  3. Geben Sie bei Signaturgeheimnis einen langen Zufallswert ein und bewahren Sie eine Kopie für Ihren Server auf.
  4. Fügen Sie unter HTTP-Header die Header hinzu, die mitgesendet werden sollen, etwa Authorization. Ihre Werte werden verschlüsselt gespeichert. Wohin sie gehen, steht unter Gut zu wissen.
  5. Wählen Sie Verbinden. Der Test antwortet Connected. Each survey and step names the endpoint it posts to.
Den Webhooks-Connector verbinden: das Signaturgeheimnis und etwaige Header.

Bleibt das Signaturgeheimnis leer, wird eines für Sie erzeugt – es wird aber nie angezeigt, sodass Sie damit keine Signaturen prüfen könnten. Geben Sie Ihr eigenes ein. Um es später zu ändern, wählen Sie Konfigurieren und tippen das neue über den gespeicherten Wert.

Einer Kampagne ihren Endpunkt geben

  1. Öffnen Sie Kampagnen, dann die Kampagne und ihren Tab Integrationen.
  2. Suchen Sie unter Verbindung hinzufügen Webhooks und wählen Sie Verbinden. Steht auf der Schaltfläche Einrichten, ist der Connector noch nicht mit dem Arbeitsbereich verbunden.
  3. Geben Sie bei Endpunkt die Adresse ein, an die die Antworten dieser Kampagne gesendet werden.
  4. Wählen Sie Änderungen speichern.
Das Ziel einer Kampagne: der Endpunkt, an den ihre Antworten gesendet werden.

Webhooks erscheint dann unter Mit dieser Kampagne verbunden, mit Sendet an und der Adresse, dem Schalter, Konfiguration bearbeiten, Trennen und der Zahl der gesendeten und fehlgeschlagenen Antworten. Jede Kampagne kann an ihren eigenen Endpunkt senden.

Der Tab Integrationen einer Kampagne: wohin jede Antwort geht und was sich hinzufügen lässt.

Was Ihr Endpunkt empfängt

Jede Antwort ist ein POST mit diesen Headern:

HeaderInhalt
Content-Typeapplication/json
X-Polzy-Eventresponse.submitted für eine Kampagnenantwort; aus einem Workflow der Ereignisname des Schritts.
X-Polzy-SignatureDer HMAC-SHA256 des unveränderten Anfrage-Bodys, mit dem Signaturgeheimnis berechnet, hexadezimal geschrieben.
X-Polzy-TimestampDer timestamp aus dem Body.
Idempotency-KeyNur aus einem Workflow-Schritt: gleich bei einer Wiederholung desselben Schritts, damit Sie sie ignorieren können.

Und diesen JSON-Body:

FeldInhalt
eventresponse.submitted.
timestampWann die Anfrage gesendet wurde. Bei einer anonymen Antwort der Tag, an dem sie gegeben wurde.
survey.id, survey.titleDie ID und der Titel der Umfrage.
response.idDie ID der Antwort in Polzy. Leer bei einer anonymen Antwort.
response.submittedAtWann die Antwort abgeschlossen wurde. Bei einer anonymen Antwort nur der Tag.
response.answersEin Eintrag je beantworteter Frage, jeweils mit questionId, questionText und value.
response.scoreDer Gesamtscore, falls er beim Senden der Anfrage schon berechnet war.

Eine anonyme Antwort enthält ihren Inhalt, ihren Score und ihren Tag und nichts, womit sich die Person erkennen oder zeitlich einordnen ließe. Polzy wartet bei jeder Antwort auf die Sicherheitsprüfung, bis zu 10 Minuten, bevor es sie sendet; eine zur Sicherheitsprüfung zurückgehaltene Antwort kommt als Platzhaltertext an. Die Mindestgruppengröße hält einzelne Antworten nicht zurück.

Die Signatur prüfen

  1. Lesen Sie den Anfrage-Body genau so, wie er angekommen ist, bevor Sie ihn parsen.
  2. Berechnen Sie seinen HMAC-SHA256 mit Ihrem Signaturgeheimnis, hexadezimal geschrieben.
  3. Vergleichen Sie ihn mit X-Polzy-Signature, mit einem Vergleich in konstanter Zeit. Weichen sie ab, lehnen Sie die Anfrage ab.

Der Zeitstempel ist Teil des Bodys – ein veränderter Zeitstempel macht also auch die Signatur ungültig.

Einen Webhook aus einem Workflow senden

  1. Öffnen Sie Workflows und den Workflow, oder legen Sie einen neuen an.
  2. Ziehen Sie unter Connectors in Installierte Schritte den Schritt Webhook senden · Webhooks auf die Arbeitsfläche.
  3. Geben Sie bei Endpunkt ein, wohin dieser Schritt sendet.
  4. Behalten Sie bei Ereignisname workflow.step oder nennen Sie das Ereignis, das Ihr Server erwartet. Es wird als X-Polzy-Event gesendet.
  5. Lassen Sie Nutzdaten leer, um alles zu senden, was der Lauf weiß, oder schreiben Sie das gewünschte JSON, mit {{ für Werte aus dem Lauf.
  6. Wählen Sie Test senden, um eine Anfrage mit einer Beispielantwort zu senden.
Der Schritt Webhook senden: der Endpunkt, der Name des Ereignisses und die Nutzdaten.

Der Schritt wird mit dem Geheimnis der Verbindung signiert und gibt die Antwort Ihres Servers als {{connector.statusCode}} und {{connector.response}} weiter.

Prüfen, ob es funktioniert

Auf dem Tab Integrationen der Kampagne zählt die Aktivitätszeile die gesendeten und die fehlgeschlagenen Antworten. Die Seite des Connectors listet jede Übermittlung unter Aktivität, mit Erfolgreich oder Fehlgeschlagen und dem Grund.

Die Seite des Connectors: Status, die letzten sieben Tage und jede Übermittlung.

Fehlerbehebung

Unter Aktivität steht bei einer fehlgeschlagenen Übermittlung Webhook failed: und der Grund; der Lauf eines Workflows zeigt denselben Grund ohne dieses Präfix.

  • Webhook failed: only https endpoints are allowed. Der Endpunkt muss mit https:// beginnen.
  • Webhook failed: private addresses are not allowed. Die Adresse zeigt in ein privates Netzwerk, etwa localhost oder 10.0.0.5. Verwenden Sie eine aus dem Internet erreichbare Adresse.
  • Webhook failed: that host could not be found. Der Name in der Adresse existiert nicht. Prüfen Sie die Schreibweise.
  • Webhook failed: mit einem Status wie 500 oder timeout of 10000ms exceeded. Ihr Endpunkt hat mit einem Fehler geantwortet oder länger als 10 Sekunden gebraucht. Alles außer einer 2xx-Antwort gilt als fehlgeschlagen, und die Übermittlung wird insgesamt dreimal versucht.
  • No endpoint for this survey. Set one on its Integrations tab. Die Kampagne hat keinen Endpunkt. Fügen Sie über Konfiguration bearbeiten auf dem Tab Integrationen der Kampagne einen hinzu.
  • Die Signatur stimmt nicht. Berechnen Sie sie über den unveränderten Body, vor jedem Parsen, mit dem Geheimnis, das Sie eingegeben haben. Wurde das Geheimnis für Sie erzeugt, geben Sie Ihr eigenes ein.
  • Ihr Header kommt nicht an. Siehe unten: Header gehen nur an einen Host, an den die Verbindung selbst sendet.

Antworten, die eingingen, bevor der Endpunkt gespeichert war, oder während der Schalter aus war, werden später nicht gesendet. Exportieren Sie sie stattdessen über Antworten der Umfrage.

Gut zu wissen

  • Wohin gehen die HTTP-Header? Nur an einen Host, an den die Verbindung selbst sendet. Ein Endpunkt, den eine Kampagne oder ein Schritt auf einem anderen Host wählt, wird ohne sie aufgerufen – ein gespeicherter Authorization-Wert erreicht so nie eine Adresse, für die er nicht gedacht war. Verlassen Sie sich auf die Signatur, um Anfragen von Polzy von allen anderen zu unterscheiden.
  • Werden unvollständige Antworten gesendet? Nein. Nur abgeschlossene Antworten, jede einmal.
  • Kann mein Endpunkt mit Daten antworten? Bei einem Workflow-Schritt ja: Die Antwort wird als {{connector.response}} für spätere Schritte aufbewahrt. Bei den Antworten einer Kampagne zählt nur ihr Status.
War das hilfreich?

Verwandte Artikel

Immer noch nicht weiter?

Angemeldete Mitglieder können Polzy fragen oder dem Team über Support schreiben. Wie schnell wir antworten, hängt von Ihrem Tarif ab.

Polzy fragenSupport kontaktieren