Standaardwebhooks instellen en beheren in Enquete

Met Standaardwebhooks kan Enquete automatisch enquêtegerelateerde informatie naar een andere applicatie verzenden wanneer een geselecteerde gebeurtenis plaatsvindt.

Wanneer een respondent bijvoorbeeld een enquête indient of voltooit, kan Enquete de gebeurtenisgegevens rechtstreeks verzenden naar uw CRM-systeem, rapportageplatform, interne database, supportapplicatie, marketingplatform of een andere externe dienst.

Hierdoor kan uw organisatie workflows automatiseren en enquêtegegevens tussen systemen verplaatsen zonder reacties steeds opnieuw te exporteren of informatie handmatig over te dragen.

In deze handleiding wordt uitgelegd hoe u Standaardwebhooks via de Enquete-interface kunt aanmaken, configureren, testen, controleren en beheren.

 

Wat is een Standaardwebhook?

Een Standaardwebhook is een geautomatiseerde verbinding tussen Enquete en een externe applicatie.

Wanneer een gebeurtenis plaatsvindt in een geselecteerde enquête, verzendt Enquete een HTTP POST-verzoek naar de endpoint-URL die in het webhookabonnement is geconfigureerd.

Afhankelijk van de workflow van uw organisatie kan een webhook worden gebruikt om:

• Nieuwe enquêtereacties naar een CRM-systeem te verzenden.
• Enquêtegegevens in een interne database op te slaan.
• Een support- of customer-success-team op de hoogte te stellen.
• Een rapportage- of analyseworkflow te starten.
• Een record in een andere applicatie aan te maken of bij te werken.
• Een aangepast intern bedrijfsproces te activeren.

Elke Standaardwebhook is gekoppeld aan een specifieke enquête en een specifiek gebeurtenistype. Hierdoor bepaalt u welke activiteiten een levering activeren en waar de informatie naartoe wordt verzonden.

 

Voordat u een webhook aanmaakt

Controleer voordat u een Standaardwebhook instelt of uw technische team het volgende heeft voorbereid:

• Een openbaar toegankelijk HTTPS-endpoint.
• Een server die HTTP POST-verzoeken kan ontvangen.
• Een proces voor het lezen van JSON-requestbody’s.
• Een beveiligde locatie voor het opslaan van het webhookgeheim.
• Een proces voor het verifiëren van webhookhandtekeningen.
• Een methode om dubbele verwerking van gebeurtenissen te voorkomen.

Het ontvangende endpoint moet snel reageren nadat een verzoek is geaccepteerd. Langdurige bewerkingen moeten normaal gesproken naar een wachtrij of achtergrondverwerkingssysteem worden doorgestuurd nadat het endpoint een succesvolle respons heeft geretourneerd.

Ontwikkelaars moeten de officiële Webhookdocumentatie raadplegen voordat zij het ontvangende endpoint implementeren.

 

Standaardwebhooks openen

Stap 1: Open Integraties

Selecteer vanuit uw Enquete-dashboard bovenaan in het menu Integraties.

Stap 2: Selecteer Standaardwebhooks

Open Standaardwebhooks vanuit de beschikbare integratieopties.

Het overzicht van Standaardwebhooks toont alle webhookabonnementen die in uw account beschikbaar zijn.

Vanaf deze pagina kunt u:

• Een nieuwe webhook aanmaken.
• Bestaande webhookabonnementen bekijken.
• Webhookinstellingen bewerken.
• Webhookgeheimen weergeven en kopiëren.
• Testleveringen verzenden.
• Leveringslogboeken bekijken.
• Een webhook activeren of deactiveren.
• Een webhook verwijderen.

 

Een Standaardwebhook aanmaken

Stap 1: Klik op Webhook toevoegen

Klik in het overzicht van Standaardwebhooks op Webhook toevoegen.

Er wordt een configuratieformulier geopend.

Stap 2: Voer de endpoint-URL in

Voer het HTTPS-endpoint in waarnaar Enquete de webhookleveringen moet verzenden.

Bijvoorbeeld:

https://example.com/api/enquete/webhook

Het endpoint moet openbaar toegankelijk zijn en HTTP POST-verzoeken kunnen accepteren.

Localhost-adressen, privé-ontwikkel-URL’s en pagina’s waarvoor interactief moet worden ingelogd, kunnen geen webhookleveringen van Enquete ontvangen.

Stap 3: Voeg een beschrijving toe

Voer een beschrijving in die duidelijk het doel van de webhook uitlegt.

Bijvoorbeeld:

Voltooide klanttevredenheidsreacties naar ons CRM-systeem verzenden

Een duidelijke beschrijving maakt het eenvoudiger om de webhook later terug te vinden, vooral wanneer uw organisatie meerdere abonnementen beheert.

Stap 4: Selecteer een enquête

Selecteer de enquête waarvan de gebeurtenissen de webhook moeten activeren.

Een Standaardwebhookabonnement is aan één enquête gekoppeld. Wanneer u gebeurtenissen van meerdere enquêtes wilt verzenden, moet u voor elke enquête een afzonderlijk webhookabonnement aanmaken.

Stap 5: Selecteer een gebeurtenistype

Selecteer de gebeurtenis die de webhooklevering moet activeren.

Gebeurtenissen die beschikbaar kunnen zijn in de interface voor Standaardwebhooks zijn onder andere:

• survey.new.response
• survey.response.completed

De beschikbare gebeurtenissen kunnen afhankelijk zijn van de huidige Enquete-configuratie en de functies die voor uw account zijn ingeschakeld.

Stap 6: Kies de activeringsstatus

Kies of de webhook onmiddellijk actief moet zijn.

Wanneer een webhook actief is, verzendt Enquete een levering wanneer de geselecteerde gebeurtenis plaatsvindt.

Wanneer de webhook inactief is, blijft de configuratie beschikbaar, maar worden leveringen van livegebeurtenissen gepauzeerd.

U kunt een webhook inactief laten terwijl uw technische team het ontvangende endpoint voorbereidt of test.

Stap 7: Sla de webhook op

Klik op Opslaan om het webhookabonnement aan te maken.

De nieuwe webhook verschijnt in het overzicht van Standaardwebhooks en kan onmiddellijk worden getest.

 

Het webhookgeheim beheren

Elke Standaardwebhook heeft een geheim. De ontvangende applicatie gebruikt dit geheim om te verifiëren dat een binnenkomend verzoek daadwerkelijk van Enquete afkomstig is.

Het webhookgeheim moet op dezelfde manier worden behandeld als een wachtwoord of persoonlijke API-referentie.

Stap 1: Geef het geheim weer

Zoek de webhook in het overzicht en klik op het oogpictogram.

Het geheim wordt tijdelijk weergegeven.

Stap 2: Kopieer het geheim

Klik op het klembordpictogram om het geheim te kopiëren.

Om veiligheidsredenen wordt het geheim na ongeveer tien seconden automatisch weer verborgen.

Stap 3: Sla het geheim veilig op

Geef het geheim door aan de ontwikkelaar die verantwoordelijk is voor het ontvangende endpoint en sla het op een beveiligde locatie aan de serverzijde op, zoals:

• Een omgevingsvariabele.
• Een versleutelde applicatieconfiguratie.
• Een cloudgeheimenbeheerder.
• Een beveiligde opslagplaats voor inloggegevens.

Sla het geheim niet op in frontend-JavaScript, openbare repositories, screenshots, gedeelde documenten of supportberichten die toegankelijk zijn voor onbevoegde gebruikers.

 

Een webhook testen

U moet elke webhook testen voordat u deze in een liveworkflow gebruikt.

Met een testlevering controleert u of het endpoint bereikbaar is en of de ontvangende server een passende respons retourneert.

Stap 1: Zoek de webhook

Zoek het webhookabonnement in het overzicht van Standaardwebhooks.

Stap 2: Verzend een testlevering

Klik op het bliksempictogram in de rij van de webhook.

Enquete verzendt een testverzoek naar het geconfigureerde endpoint.

Stap 3: Bekijk het resultaat

In een melding op de pagina wordt de HTTP-status weergegeven die door het endpoint is geretourneerd.

Een succesvolle levering retourneert normaal gesproken een statuscode binnen het bereik van 200 tot en met 299, zoals:

• 200 OK
• 201 Created
• 202 Accepted
• 204 No Content

Wanneer de test mislukt, opent u de leveringslogboeken om de responsstatus, responsbody, foutinformatie en duur van het verzoek te controleren.

 

Een webhook bewerken

U kunt een bestaande webhook bijwerken wanneer het endpoint, de enquête, het gebeurtenistype, de beschrijving of de activeringsstatus verandert.

Stap 1: Klik op Bewerken

Zoek de webhook en selecteer de actie Bewerken.

Stap 2: Werk de instellingen bij

U kunt instellingen bijwerken, zoals:

• De endpoint-URL.
• De beschrijving van de webhook.
• De geselecteerde enquête.
• Het gebeurtenistype.
• De actieve of inactieve status.

Stap 3: Sla de wijzigingen op

Sla de webhook op nadat u de wijzigingen heeft aangebracht.

De bijgewerkte configuratie wordt voor toekomstige leveringen gebruikt.

Verzend altijd opnieuw een testlevering nadat u de endpoint-URL, enquête of het gebeurtenistype heeft gewijzigd.

 

Leveringslogboeken bekijken

De leveringslogboeken tonen de verzoeken die Enquete naar uw endpoint heeft verzonden en de responsen die door de ontvangende server zijn geretourneerd.

Gebruik deze logboeken om de werking van uw integratie te controleren en mislukte leveringen te onderzoeken.

Stap 1: Open de logboeken

Zoek het webhookabonnement en klik naast de verwijderknop op het pictogram Logboeken bekijken.

Stap 2: Filter de leveringsgeschiedenis

U kunt leveringen filteren op:

• Alle
• Geslaagd
• Mislukt

Stap 3: Controleer een levering

Vouw een leveringsitem uit om de beschikbare diagnostische informatie te bekijken.

Het leveringsrecord kan de volgende informatie bevatten:

• De requestpayload.
• De HTTP-responsstatus.
• De responsbody die door de ontvangende server is geretourneerd.
• Een foutmelding.
• De duur van de levering in milliseconden.
• Het nummer van de leveringspoging.
• De unieke leverings-ID.

Leveringslogboeken zijn vooral nuttig na:

• Het aanmaken van een nieuwe webhook.
• Het wijzigen van een endpoint-URL.
• Het implementeren van een update van de ontvangende applicatie.
• Het wijzigen van firewall- of serverinstellingen.
• Het onderzoeken van ontbrekende enquêtegegevens.
• Het onderzoeken van trage of mislukte leveringen.

 

Webhookheaders begrijpen

Elk webhookverzoek bevat headers waarmee de ontvangende applicatie de levering kan identificeren, verifiëren en volgen.

Header	Beschrijving
X-Enquete-Signature	Bevat de handtekening waarmee wordt geverifieerd dat het verzoek van Enquete afkomstig is.
X-Enquete-Event	Identificeert het gebeurtenistype dat de levering heeft geactiveerd.
X-Enquete-Delivery	Bevat een unieke leverings-ID die wordt gebruikt voor tracking en het voorkomen van dubbele verwerking.

Uw technische team moet de handtekeningheader gebruiken om binnenkomende verzoeken te authenticeren en de leveringsheader gebruiken om te voorkomen dat dezelfde gebeurtenis meer dan één keer wordt verwerkt.

Raadpleeg voor de exacte indeling van de handtekening, het payloadschema en implementatievoorbeelden de officiële Webhookdocumentatie.

 

Dubbele leveringen begrijpen

Een webhooklevering kan meer dan één keer worden geprobeerd wanneer het eerste verzoek mislukt, een time-out veroorzaakt of geen succesvolle respons retourneert.

Dit betekent dat de ontvangende applicatie een levering die al is verwerkt moet kunnen herkennen en veilig moet kunnen negeren.

Elk verzoek bevat een unieke waarde in de header X-Enquete-Delivery.

Uw technische team moet deze waarde als idempotentiesleutel gebruiken.

Een gebruikelijk proces voor het voorkomen van dubbele verwerking is:

1. Lees de waarde van X-Enquete-Delivery.
2. Controleer of de leverings-ID al is verwerkt.
3. Wanneer de levering al is verwerkt, retourneert u een succesvolle respons zonder de actie opnieuw uit te voeren.
4. Wanneer de levering nog niet is verwerkt, slaat u de leverings-ID op en verwerkt u de gebeurtenis.

Verwerkte leverings-ID’s moeten worden bewaard gedurende een periode die past bij het integratie- en retrybeleid van uw organisatie.

 

Een webhook deactiveren

Deactiveer een webhook wanneer u leveringen tijdelijk wilt stoppen zonder de configuratie te verwijderen.

U kunt een webhook deactiveren wanneer:

• Onderhoud wordt uitgevoerd aan de ontvangende applicatie.
• Uw technische team het endpoint vervangt.
• De gekoppelde workflow tijdelijk is gepauzeerd.
• U herhaaldelijke fouten onderzoekt.
• De webhook momenteel niet nodig is.

Wanneer de webhook opnieuw wordt geactiveerd, kunnen toekomstige overeenkomende gebeurtenissen worden geleverd.

Gebeurtenissen die plaatsvinden terwijl de webhook inactief is, worden mogelijk niet automatisch op een later moment geleverd.

 

Een webhook verwijderen

Verwijder een webhook wanneer het abonnement niet langer nodig is.

Stap 1: Selecteer Verwijderen

Zoek de webhook en klik op de actie Verwijderen.

Stap 2: Bevestig de verwijdering

Bevestig dat u het webhookabonnement permanent wilt verwijderen.

Na de verwijdering verzendt Enquete geen nieuwe leveringen meer voor deze webhook.

Historische leveringsrecords kunnen voor audit-, probleemoplossings- of operationele doeleinden in backendrecords beschikbaar blijven.

Belangrijk: Wanneer u de webhook alleen tijdelijk wilt pauzeren, moet u deze deactiveren in plaats van verwijderen.

 

Problemen met Standaardwebhooks oplossen

De webhooklevering mislukt of veroorzaakt een time-out

Controleer het volgende:

• Controleer of het endpoint openbaar toegankelijk is.
• Controleer of het endpoint HTTPS gebruikt.
• Controleer of een firewall- of beveiligingsregel het verzoek blokkeert.
• Controleer of het endpoint HTTP POST-verzoeken accepteert.
• Zorg ervoor dat de ontvangende server snel reageert.
• Bekijk de responsstatus en foutmelding in de leveringslogboeken.
• Controleer of de ontvangende applicatie momenteel beschikbaar is.

Langdurige taken moeten in een wachtrij worden geplaatst voor achtergrondverwerking, in plaats van volledig te worden uitgevoerd voordat de server zijn respons retourneert.

De webhookhandtekening is ongeldig

Vraag uw technische team om het volgende te controleren:

• Het geheim behoort tot het juiste webhookabonnement.
• De onbewerkte requestbody wordt voor de handtekeningverificatie gebruikt.
• De JSON-body wordt niet opnieuw opgemaakt voordat deze wordt geverifieerd.
• De verwachte indeling van de handtekening komt overeen met de door Enquete gedocumenteerde indeling.

Handtekeningverificatie is een technische implementatietaak. Raadpleeg de officiële Webhookdocumentatie voor de actuele verificatie-instructies.

Er worden geen webhookleveringen ontvangen

Controleer het volgende:

• Controleer of de webhook actief is.
• Controleer of de juiste enquête is geselecteerd.
• Controleer of de geselecteerde gebeurtenis daadwerkelijk heeft plaatsgevonden.
• Controleer of de endpoint-URL correct is.
• Verzend een testlevering.
• Open de leveringslogboeken om te controleren of er een verzoek is verzonden.

Het endpoint retourneert een 401- of 403-respons

Een 401- of 403-respons betekent normaal gesproken dat de ontvangende server het verzoek heeft geweigerd vanwege een authenticatie- of autorisatieregel.

Controleer of:

• Het endpoint een niet-ondersteunde authenticatiemethode vereist.
• Een firewall of API-gateway het verzoek afwijst.
• Het endpoint alleen verzoeken van geselecteerde netwerken accepteert.
• Het handtekeningverificatieproces geldige verzoeken ten onrechte afwijst.

Het endpoint retourneert een 404-respons

Een 404-respons betekent meestal dat de endpoint-URL niet overeenkomt met een beschikbare route op de ontvangende server.

Controleer de volledige URL en bevestig dat de route bestaat en HTTP POST-verzoeken accepteert.

Het endpoint retourneert een 500-respons

Een 500-respons geeft aan dat er binnen de ontvangende applicatie een fout is opgetreden.

Uw technische team moet de serverlogboeken van de ontvangende applicatie bekijken, samen met de leveringspayload en leverings-ID die in Enquete worden weergegeven.

Dezelfde gebeurtenis wordt meer dan één keer verwerkt

Webhookverzoeken kunnen na fouten of time-outs opnieuw worden geprobeerd.

Uw technische team moet de waarde X-Enquete-Delivery gebruiken om leveringen te identificeren die al zijn verwerkt.

 

Best practices voor webhookbeveiliging

• Gebruik altijd een HTTPS-endpoint.
• Verifieer de webhookhandtekening voordat u een verzoek verwerkt.
• Sla het webhookgeheim alleen op in beveiligde systemen aan de serverzijde.
• Stel het geheim nooit beschikbaar in frontendcode.
• Gebruik de onbewerkte requestbody tijdens de handtekeningverificatie.
• Gebruik de leverings-ID om dubbele verwerking te voorkomen.
• Retourneer snel een succesvolle respons.
• Verwerk langdurige bewerkingen asynchroon.
• Controleer mislukte leveringen en ongewoon trage responsen.
• Bekijk de leveringslogboeken nadat updates voor het endpoint zijn geïmplementeerd.
• Test de webhook na elke configuratiewijziging.
• Deactiveer webhookabonnementen die tijdelijk niet worden gebruikt.
• Verwijder abonnementen die niet langer nodig zijn.

 

Checklist voordat u een webhook activeert

Controleer voordat u een Standaardwebhook in een liveworkflow gebruikt of u het volgende heeft voltooid:

1. Maak de webhook aan met het juiste HTTPS-endpoint.
2. Selecteer de juiste enquête.
3. Selecteer het juiste gebeurtenistype.
4. Kopieer het webhookgeheim en sla het veilig op.
5. Implementeer handtekeningverificatie op de ontvangende server.
6. Implementeer bescherming tegen dubbele leveringen.
7. Verzend een testlevering.
8. Controleer of het endpoint een succesvolle respons retourneert.
9. Bekijk de verzoek- en responsdetails in de leveringslogboeken.
10. Stel monitoring en foutmeldingen voor het ontvangende endpoint in.
11. Activeer de webhook voor live-enquêtegebeurtenissen.

Nadat de webhook live is gegaan, moet u mislukte leveringen en de prestaties van het endpoint regelmatig controleren om er zeker van te zijn dat de integratie correct blijft werken.

Raadpleeg voor payloadvelden, gebeurtenisschema’s, voorbeelden voor handtekeningverificatie en andere ontwikkelaarsspecifieke instructies altijd de officiële Enquete-webhookdocumentatie.