Envoyer les réponses vers votre endpoint par webhook
Envoyez chaque réponse reçue par une campagne, signée, vers une adresse HTTPS à vous, ou n’importe quelle charge utile depuis une étape de workflow. En quoi le connecteur Webhooks diffère de Paramètres → API → Webhooks.
Sur cette page
Le connecteur Webhooks envoie chaque réponse reçue par une campagne vers une adresse de votre propre serveur, sous forme de POST signé, quelques instants après qu’elle a été donnée. Un workflow peut aussi l’utiliser, pour envoyer tout ce que l’exécution connaît. À la fin de ce guide, vous aurez un endpoint qui reçoit les réponses, et le moyen de vérifier que chaque requête vient bien de Polzy.
Le connecteur Webhooks est inclus dans l’offre Business. Seul un Administrateur peut le connecter et choisir où vont les réponses d’une campagne.
De quel webhook avez-vous besoin ?
Polzy peut appeler votre serveur de trois façons :
| Connecteur Webhooks (cet article) | Paramètres → API → Webhooks | Étape Webhook sortant | |
|---|---|---|---|
| Ce qui est envoyé | Chaque réponse d’une campagne, ou la charge utile d’une étape de workflow | Des événements de l’espace de travail : une réponse créée, une campagne terminée, une action créée ou terminée | Ce que dit l’étape du workflow |
| Où le régler | Intégrations, puis l’onglet Intégrations d’une campagne ou une étape de workflow | Paramètres → API → Webhooks | Un workflow |
| Offre | Business | Équipe | Équipe |
| Signé | X-Polzy-Signature, sur le corps | X-Polzy-Signature, sur l’horodatage et le corps | Non |
| En cas d’échec | Trois tentatives au total | Six tentatives sur environ une demi-heure, avec un journal de chaque essai | La règle d’erreur de l’étape décide |
Pour les événements de tout l’espace de travail, voir Envoyer et recevoir des webhooks.
Avant de commencer
Il vous faut :
- Un espace de travail sur l’offre Business, avec le rôle Administrateur.
- Intégrations activé pour l’espace de travail, dans Paramètres → Général → Ce que fait cet espace de travail.
- Un endpoint sur internet, en HTTPS, qui accepte un
POSTavec un corps JSON et répond par un statut 2xx en moins de 10 secondes. Polzy refuse les adresseshttp://et celles d’un réseau privé.
Connecter le connecteur Webhooks
La connexion conserve ce que partagent toutes les requêtes : le secret de signature, et d’éventuels en-têtes.
- Dans la barre latérale, sous Automatiser, ouvrez Intégrations et choisissez l’onglet Disponibles.
- Trouvez Webhooks et choisissez Connecter.
- Dans Secret de signature, saisissez une longue valeur aléatoire et gardez-en une copie pour votre serveur.
- Sous En-têtes HTTP, ajoutez les en-têtes à envoyer, comme
Authorization. Leurs valeurs sont stockées chiffrées. Voir Bon à savoir pour savoir où ils vont. - Choisissez Connecter. Le test répond Connected. Each survey and step names the endpoint it posts to.
Laissé vide, le secret de signature est créé pour vous — mais il n’est jamais affiché, et vous ne pourriez pas vérifier les signatures avec. Saisissez le vôtre. Pour le changer plus tard, choisissez Configurer et tapez le nouveau par-dessus la valeur enregistrée.
Donner son endpoint à une campagne
- Ouvrez Campagnes, puis la campagne et son onglet Intégrations.
- Sous Ajouter une connexion, trouvez Webhooks et choisissez Connecter. Si le bouton indique Configurer, le connecteur n’est pas encore connecté à l’espace de travail.
- Dans Destination, saisissez l’adresse à laquelle les réponses de cette campagne sont envoyées.
- Choisissez Enregistrer les modifications.
Webhooks apparaît alors sous Connecté à cette campagne, avec Envoie vers et l’adresse, son interrupteur, Modifier la configuration, Déconnecter, et le nombre de réponses envoyées et en échec. Chaque campagne peut envoyer vers son propre endpoint.
Ce que reçoit votre endpoint
Chaque réponse est un POST avec ces en-têtes :
| En-tête | Contenu |
|---|---|
Content-Type | application/json |
X-Polzy-Event | response.submitted pour une réponse de campagne ; le Nom de l'événement de l’étape depuis un workflow. |
X-Polzy-Signature | Le HMAC-SHA256 du corps brut de la requête, calculé avec le secret de signature, en hexadécimal. |
X-Polzy-Timestamp | Le timestamp du corps. |
Idempotency-Key | Depuis une étape de workflow uniquement : identique lors d’une répétition de la même étape, pour que vous puissiez l’ignorer. |
Et ce corps JSON :
| Champ | Contenu |
|---|---|
event | response.submitted. |
timestamp | Le moment où la requête a été envoyée. Pour une réponse anonyme, le jour où elle a été donnée. |
survey.id, survey.title | L’identifiant et le titre de l’enquête. |
response.id | L’identifiant de la réponse dans Polzy. Vide pour une réponse anonyme. |
response.submittedAt | Le moment où la réponse a été terminée. Pour une réponse anonyme, le jour seulement. |
response.answers | Un élément par question répondue, chacun avec questionId, questionText et value. |
response.score | Le score global, s’il était calculé au moment de l’envoi de la requête. |
Une réponse anonyme contient ce qu’elle dit, son score et son jour, et rien qui permette d’identifier ou de dater son auteur. Polzy attend la lecture de sécurité de chaque réponse, jusqu’à 10 minutes, avant de l’envoyer ; une réponse retenue pour examen de sécurité arrive sous forme de texte de remplacement. La taille minimale des groupes ne retient pas les réponses individuelles.
Vérifier la signature
- Lisez le corps de la requête exactement tel qu’il est arrivé, avant de l’analyser.
- Calculez son HMAC-SHA256 avec votre secret de signature, en hexadécimal.
- Comparez-le à
X-Polzy-Signature, avec une comparaison à temps constant. S’ils diffèrent, refusez la requête.
L’horodatage fait partie du corps : un horodatage modifié invalide donc aussi la signature.
Envoyer un webhook depuis un workflow
- Ouvrez Workflows et le workflow, ou créez-en un.
- Sous Connecteurs dans Étapes installées, faites glisser Envoyer un webhook · Webhooks sur le canevas.
- Dans Point de terminaison, saisissez l’adresse vers laquelle cette étape envoie.
- Sous Nom de l'événement, gardez
workflow.stepou nommez l’événement qu’attend votre serveur. Il est envoyé dansX-Polzy-Event. - Laissez Charge utile vide pour envoyer tout ce que l’exécution connaît, ou écrivez le JSON voulu, avec
{{pour insérer des valeurs de l’exécution. - Choisissez Envoyer un test pour envoyer une requête remplie à partir d’une réponse d’exemple.
L’étape est signée avec le secret de la connexion et transmet la réponse de votre serveur sous la forme {{connector.statusCode}} et {{connector.response}}.
Vérifier que tout fonctionne
Dans l’onglet Intégrations de la campagne, la ligne d’activité compte les réponses envoyées et celles qui ont échoué. La page du connecteur liste chaque envoi dans Activité, avec Réussi ou Échec et la raison.
Dépannage
Dans Activité, un envoi en échec indique Webhook failed: suivi de la raison ; l’exécution d’un workflow affiche la même raison sans ce préfixe.
- Webhook failed: only https endpoints are allowed. L’endpoint doit commencer par
https://. - Webhook failed: private addresses are not allowed. L’adresse pointe vers un réseau privé, comme
localhostou10.0.0.5. Utilisez une adresse accessible depuis internet. - Webhook failed: that host could not be found. Le nom dans l’adresse n’existe pas. Vérifiez son orthographe.
- Webhook failed: suivi d’un statut, comme
500, ou timeout of 10000ms exceeded. Votre endpoint a répondu par une erreur, ou a mis plus de 10 secondes. Toute réponse autre que 2xx compte comme un échec, et l’envoi est tenté trois fois au total. - No endpoint for this survey. Set one on its Integrations tab. La campagne n’a pas d’endpoint. Ajoutez-en un avec Modifier la configuration dans l’onglet Intégrations de la campagne.
- La signature ne correspond pas. Calculez-la sur le corps brut, avant toute analyse, avec le secret que vous avez saisi. Si le secret a été créé pour vous, saisissez le vôtre.
- Votre en-tête n’arrive pas. Voir ci-dessous : les en-têtes ne partent que vers un hôte auquel la connexion elle-même envoie.
Les réponses reçues avant l’enregistrement de l’endpoint, ou pendant que l’interrupteur était coupé, ne sont pas envoyées plus tard. Exportez-les plutôt depuis l’onglet Réponses de l’enquête.
Bon à savoir
- Où vont les en-têtes HTTP ? Seulement vers un hôte auquel la connexion elle-même envoie. Un endpoint qu’une campagne ou une étape choisit sur un autre hôte est appelé sans eux : une valeur
Authorizationenregistrée n’atteint jamais une adresse à laquelle elle n’était pas destinée. Comptez sur la signature pour distinguer les requêtes de Polzy de toutes les autres. - Les réponses inachevées sont-elles envoyées ? Non. Seules les réponses terminées le sont, une fois chacune.
- Mon endpoint peut-il répondre avec des données ? Pour une étape de workflow, oui : la réponse est conservée sous la forme
{{connector.response}}pour les étapes suivantes. Pour les réponses d’une campagne, seul son statut compte.
Articles liés
Les membres connectés peuvent demander à Polzy ou écrire à l’équipe depuis Support. Notre délai de réponse dépend de votre forfait.