Naar de inhoud
polzyHelpNaar Polzy

Antwoorden met webhooks naar je eigen endpoint sturen

Post elk antwoord dat een campagne ontvangt ondertekend naar een HTTPS-adres van jou, of stuur elke payload vanuit een workflowstap. Zo verschilt de Webhooks-connector van Instellingen → API → Webhooks.

Polzy-team7 min lezenBijgewerkt 31 okt 2026Business en hoger
Op deze pagina
  1. 1Welke webhook heb je nodig?
  2. 2Voordat je begint
  3. 3De Webhooks-connector koppelen
  4. 4Een campagne haar endpoint geven
  5. 5Wat je endpoint ontvangt
  6. 6De handtekening controleren
  7. 7Een webhook versturen vanuit een workflow
  8. 8Controleren of het werkt
  9. 9Problemen oplossen
  10. 10Goed om te weten

De connector Webhooks stuurt elk antwoord dat een campagne ontvangt naar een adres op je eigen server, als ondertekende POST, enkele ogenblikken nadat het gegeven is. Een workflow kan hem ook gebruiken, om alles te sturen wat de run weet. Aan het eind van deze handleiding heb je een endpoint dat antwoorden ontvangt, en de middelen om te controleren dat elk verzoek echt van Polzy komt.

De Webhooks-connector hoort bij Business. Alleen een Beheerder kan hem koppelen en kiezen waar de antwoorden van een campagne heen gaan.

Welke webhook heb je nodig?

Polzy kan je server op drie manieren aanroepen:

Webhooks-connector (dit artikel)Instellingen → API → WebhooksStap Uitgaande webhook
Wat er wordt verstuurdElk antwoord van één campagne, of de payload van een workflowstapGebeurtenissen in de werkruimte: een antwoord aangemaakt, een campagne afgerond, een actie aangemaakt of afgerondWat de workflowstap zegt
Waar je het insteltIntegraties, dan het tabblad Integraties van een campagne of een workflowstapInstellingen → API → WebhooksEen workflow
AbonnementBusinessTeamTeam
OndertekendX-Polzy-Signature, over de bodyX-Polzy-Signature, over het tijdstempel en de bodyNee
Als levering misluktIn totaal drie keer geprobeerdZes keer geprobeerd in ongeveer een half uur, met een logboek van elke pogingDe foutregel van de stap beslist

Voor gebeurtenissen in de hele werkruimte, zie Webhooks versturen en ontvangen.

Voordat je begint

Je hebt nodig:

  • Een werkruimte op Business, en de rol Beheerder daarin.
  • Integraties aangezet voor de werkruimte, onder Instellingen → Algemeen → Wat deze werkruimte doet.
  • Een endpoint op internet, via HTTPS, dat een POST met een JSON-body accepteert en binnen 10 seconden met een 2xx-status antwoordt. Polzy weigert http://-adressen en adressen binnen een privénetwerk.

De Webhooks-connector koppelen

Bij het koppelen bewaar je wat elk verzoek deelt: het ondertekeningsgeheim en eventuele headers.

  1. Open in de zijbalk onder Automatiseren de pagina Integraties en kies het tabblad Beschikbaar.
  2. Zoek Webhooks en kies Verbinden.
  3. Vul bij Ondertekeningsgeheim een lange willekeurige waarde in en bewaar een kopie voor je server.
  4. Voeg onder HTTP-headers de headers toe die je wilt meesturen, zoals Authorization. Hun waarden worden versleuteld opgeslagen. Zie Goed om te weten voor waar ze heen gaan.
  5. Kies Verbinden. De test antwoordt Connected. Each survey and step names the endpoint it posts to.
De Webhooks-connector koppelen: het ondertekeningsgeheim en eventuele headers.

Laat je het ondertekeningsgeheim leeg, dan wordt er een voor je gemaakt — maar dat wordt nooit getoond, dus je zou er geen handtekeningen mee kunnen controleren. Vul je eigen geheim in. Wil je het later wijzigen, kies dan Configureren en typ het nieuwe over de bewaarde waarde heen.

Een campagne haar endpoint geven

  1. Open Campagnes, dan de campagne en haar tabblad Integraties.
  2. Zoek onder Koppeling toevoegen naar Webhooks en kies Verbinden. Staat er Instellen op de knop, dan is de connector nog niet aan de werkruimte gekoppeld.
  3. Vul bij Eindpunt het adres in waar de antwoorden van deze campagne naartoe worden gepost.
  4. Kies Wijzigingen opslaan.
De bestemming van een campagne: het endpoint waar haar antwoorden naartoe worden gepost.

Webhooks staat daarna onder Gekoppeld aan deze campagne, met Stuurt naar en het adres, de schakelaar, Configuratie bewerken, Verbinding verbreken, en hoeveel antwoorden er zijn verstuurd en mislukt. Elke campagne kan naar haar eigen endpoint posten.

Het tabblad Integraties van een campagne: waar elk antwoord heen gaat, en wat je nog kunt toevoegen.

Wat je endpoint ontvangt

Elk antwoord is één POST met deze headers:

HeaderWat erin staat
Content-Typeapplication/json
X-Polzy-Eventresponse.submitted voor een antwoord van een campagne; de Gebeurtenisnaam van de stap vanuit een workflow.
X-Polzy-SignatureDe HMAC-SHA256 van de ruwe body van het verzoek, gemaakt met het ondertekeningsgeheim, in hexadecimale notatie.
X-Polzy-TimestampDe timestamp uit de body.
Idempotency-KeyAlleen vanuit een workflowstap: gelijk bij een herhaling van dezelfde stap, zodat je die kunt negeren.

En deze JSON-body:

VeldWat erin staat
eventresponse.submitted.
timestampWanneer het verzoek werd verstuurd. Bij een anoniem antwoord de dag waarop het gegeven is.
survey.id, survey.titleDe ID en de titel van de enquête.
response.idDe ID van het antwoord in Polzy. Leeg bij een anoniem antwoord.
response.submittedAtWanneer het antwoord werd afgerond. Bij een anoniem antwoord alleen de dag.
response.answersEén item per beantwoorde vraag, elk met questionId, questionText en value.
response.scoreDe totaalscore, als die berekend was toen het verzoek werd verstuurd.

Een anoniem antwoord bevat wat er gezegd is, de score en de dag, en niets waarmee de schrijver te herkennen of in de tijd te plaatsen is. Polzy wacht bij elk antwoord op de veiligheidscontrole, tot 10 minuten, voordat het wordt verstuurd; een antwoord dat voor veiligheidsbeoordeling wordt achtergehouden, komt aan als plaatsvervangende tekst. De minimale groepsgrootte houdt losse antwoorden niet tegen.

De handtekening controleren

  1. Lees de body van het verzoek precies zoals die binnenkwam, voordat je hem verwerkt.
  2. Bereken er de HMAC-SHA256 van met je ondertekeningsgeheim, in hexadecimale notatie.
  3. Vergelijk die met X-Polzy-Signature, met een vergelijking in constante tijd. Wijken ze af, weiger het verzoek dan.

Het tijdstempel maakt deel uit van de body, dus een gewijzigd tijdstempel breekt ook de handtekening.

Een webhook versturen vanuit een workflow

  1. Open Workflows en de workflow, of begin een nieuwe.
  2. Sleep onder Connectors in Geïnstalleerde stappen de stap Webhook versturen · Webhooks naar het canvas.
  3. Vul bij Endpoint in waar deze stap naartoe post.
  4. Houd bij Gebeurtenisnaam workflow.step aan of noem de gebeurtenis die je server verwacht. Die wordt verstuurd als X-Polzy-Event.
  5. Laat Inhoud leeg om alles te sturen wat de run weet, of schrijf de JSON die je wilt, met {{ om waarden uit de run in te voegen.
  6. Kies Test versturen om één verzoek te posten dat gevuld is met een voorbeeldantwoord.
De stap Webhook versturen: het endpoint, de naam van de gebeurtenis en de payload.

De stap wordt ondertekend met het geheim van de koppeling en geeft het antwoord van je server door als {{connector.statusCode}} en {{connector.response}}.

Controleren of het werkt

Op het tabblad Integraties van de campagne telt de activiteitsregel de verstuurde en de mislukte antwoorden. De eigen pagina van de connector toont elke levering onder Activiteit, met Gelukt of Mislukt en de reden.

De pagina van de connector: de status, de laatste zeven dagen en elke levering.

Problemen oplossen

Onder Activiteit staat bij een mislukte levering Webhook failed: en de reden; de run van een workflow toont dezelfde reden zonder dat voorvoegsel.

  • Webhook failed: only https endpoints are allowed. Het endpoint moet beginnen met https://.
  • Webhook failed: private addresses are not allowed. Het adres wijst naar een privénetwerk, zoals localhost of 10.0.0.5. Gebruik een adres dat vanaf internet bereikbaar is.
  • Webhook failed: that host could not be found. De naam in het adres bestaat niet. Controleer de spelling.
  • Webhook failed: met een status, zoals 500, of timeout of 10000ms exceeded. Je endpoint antwoordde met een fout, of deed er langer dan 10 seconden over. Alles behalve een 2xx-antwoord telt als mislukt, en de levering wordt in totaal drie keer geprobeerd.
  • No endpoint for this survey. Set one on its Integrations tab. De campagne heeft geen endpoint. Voeg er een toe met Configuratie bewerken op het tabblad Integraties van de campagne.
  • De handtekening klopt niet. Bereken haar over de ruwe body, vóór enige verwerking, met het geheim dat je hebt ingevuld. Is het geheim voor je gemaakt, vul dan je eigen geheim in.
  • Je header komt niet aan. Zie hieronder: headers gaan alleen naar een host waar de koppeling zelf naartoe post.

Antwoorden die binnenkwamen voordat het endpoint was opgeslagen, of terwijl de schakelaar uit stond, worden later niet verstuurd. Exporteer ze in plaats daarvan vanuit Antwoorden van de enquête.

Goed om te weten

  • Waar gaan de HTTP-headers heen? Alleen naar een host waar de koppeling zelf naartoe post. Een endpoint dat een campagne of een stap op een andere host kiest, wordt zonder headers aangeroepen, zodat een bewaarde Authorization-waarde nooit een adres bereikt waarvoor ze niet bedoeld was. Vertrouw op de handtekening om de verzoeken van Polzy van die van anderen te onderscheiden.
  • Worden onvoltooide antwoorden verstuurd? Nee. Alleen afgeronde antwoorden, elk één keer.
  • Kan mijn endpoint met gegevens antwoorden? Voor een workflowstap wel: het antwoord wordt bewaard als {{connector.response}} voor latere stappen. Voor de antwoorden van een campagne telt alleen de status van het antwoord.
Was dit nuttig?

Gerelateerde artikelen

Kom je er niet uit?

Ingelogde leden kunnen het Polzy vragen of het team een bericht sturen via Support. Hoe snel we antwoorden, hangt af van je abonnement.

Vraag het PolzyNeem contact op