Intégrations par webhooks

Les webhooks envoient des événements de Deskwoot vers une URL de votre choix, au moment où ils se produisent : une nouvelle conversation, un nouveau message, une attribution, une conversation résolue, une modification d'un contact, une note CSAT ou une modification d'un ticket. Deskwoot envoie chaque événement en JSON dans une requête POST et le signe, pour que votre endpoint puisse vérifier qu'il vient bien de Deskwoot. Utilisez les webhooks pour garder un CRM à jour, lancer vos propres automatisations ou enregistrer les événements du support dans votre propre base de données, sans devoir demander sans cesse à l'API s'il y a du nouveau.

Quel forfait il vous faut

Les webhooks demandent le forfait Startup ou un forfait supérieur, et l'essai gratuit les inclut. Avec le forfait gratuit Hacker, les webhooks créés avant restent dans la liste sous Paramètres > Webhooks et vous pouvez les supprimer, mais ils n'envoient rien tant que votre forfait n'inclut pas de nouveau les webhooks. Ensuite, ils recommencent à envoyer d'eux-mêmes.

Un webhook ne fait qu'envoyer des données hors de Deskwoot. Pour que votre propre serveur ou n8n réponde aux messages des clients comme un bot, ajoutez un bot Custom Webhook sous Paramètres > IA > Autres bots, ce qui demande un forfait payant (Startup ou supérieur). Deskwoot envoie chaque message du client à votre URL et publie la réponse renvoyée par votre serveur, ou transmet la conversation à votre équipe. Chaque conversation à laquelle le bot répond compte comme 1 conversation IA. Quand vos conversations IA sont épuisées, le bot ne répond plus et la conversation passe à votre équipe.

Pour répondre aux messages des clients, attribuer, étiqueter ou résoudre une conversation ou mettre à jour un contact depuis votre propre code ou depuis un outil comme n8n, Make ou Zapier, vous appelez l'API REST de Deskwoot. L'API REST demande un forfait Enterprise payant, et l'essai gratuit n'inclut pas l'accès à l'API. Chaque conversation à laquelle vous répondez par ce biais compte comme 1 conversation IA. Pour créer un jeton : Jetons d'API et accès développeur.

Créer un webhook

1. Allez dans Paramètres > Webhooks. Seuls les administrateurs voient cette page.
2. Cliquez sur Ajouter un webhook.
3. Dans URL de l'endpoint, saisissez l'adresse qui doit recevoir les événements. Il doit s'agir d'une URL HTTPS publique.
4. Dans S'abonner aux événements, cochez les événements voulus. Si vous n'en cochez aucun, le webhook reçoit tous les événements sauf ceux des tickets.
5. Cliquez sur Créer un webhook.

Dès lors, Deskwoot envoie une requête POST avec un corps JSON à votre URL chaque fois qu'un événement correspondant se produit. L'interrupteur à côté d'un webhook le désactive puis le réactive, et Modifier change son URL ou ses événements. La liste indique combien d'événements reçoit chaque webhook, par exemple 3 événements, ou Tous les événements sauf ceux des tickets quand aucun n'est coché (Tous les événements tant que les tickets sont désactivés).

Événements des tickets

Tant que les tickets sont activés, S'abonner aux événements affiche aussi Tickets avec Ticket créé, Ticket mis à jour, Ticket attribué et Ticket résolu. Un ticket relève du travail interne de votre équipe, il n'envoie donc jamais d'événement de conversation. Chaque modification d'un ticket envoie à la place son événement de ticket, et seulement aux webhooks qui le cochent. Un webhook sans événement coché ne reçoit aucun événement de ticket, donc un webhook créé avant les tickets continue de recevoir uniquement les conversations avec les clients.

• Un commentaire sur un ticket est un événement Message créé avec conversationKind TICKET. Il ne va qu'aux webhooks qui cochent Message créé et au moins un événement de ticket.
• Les données contiennent ticketId et ticket, c'est-à-dire le ticket tel qu'il est au moment où l'événement part : numéro, titre, statut, priorité, catégorie, équipe, responsable, créateur, son propre statut du ticket, étiquettes, attributs personnalisés, la conversation d'origine, ainsi que ses tickets groupés et tickets Jira. Ticket mis à jour ajoute changes et source, Ticket attribué ajoute le nouveau et l'ancien responsable, et Ticket résolu ajoute qui l'a résolu.
• Le texte du résumé du ticket n'est jamais envoyé. Quand le résumé change, changes.summary vaut simplement true.
• Un ticket groupé est un ticket avec tracker à true et sans contact. Lier une conversation ou un ticket à un ticket groupé, ou le dissocier, envoie le Ticket mis à jour du ticket groupé avec changes.links. Créer, lier ou dissocier un ticket Jira, ainsi que chacun de ses nouveaux statuts, envoie Ticket mis à jour avec changes.linkedIssues.

Conseils

• Abonnez-vous seulement à ce dont vous avez besoin. Chaque événement est une requête vers votre endpoint, et moins de requêtes facilitent la recherche d'erreurs.
• Répondez vite. Renvoyez un statut 2xx dès que la requête arrive et faites le gros du travail dans une tâche en arrière-plan. Deskwoot attend 10 secondes au maximum.
• Enregistrez les payloads bruts pendant le développement, pour voir la structure exacte de chaque événement.
• Faites en sorte qu'une deuxième livraison soit sans effet. Dans de rares cas, un événement arrive deux fois, donc le traiter à nouveau ne doit pas créer de doublons.

Résolution des problèmes

• Aucun événement n'arrive ? Vérifiez que l'URL est correcte, accessible depuis Internet et qu'elle répond avec 2xx. Un pare-feu ou une liste d'IP autorisées peut bloquer les requêtes sans afficher d'erreur de votre côté. Avec le forfait gratuit Hacker, les webhooks n'envoient rien du tout.
• Le corps semble incorrect ? Lisez-le comme du JSON (Content-Type: application/json) et cherchez des erreurs de lecture dans les journaux de votre serveur.
• Les événements arrivent en retard ? Deskwoot envoie chaque événement tout de suite, et une nouvelle tentative a lieu 5 secondes après une livraison en échec. Si les événements continuent d'arriver en retard, vérifiez si votre serveur limite ou met en file d'attente les connexions entrantes.

Questions fréquentes

Quel forfait me faut-il pour les webhooks ?

Startup ou supérieur. Les webhooks demandent le forfait Startup ou un forfait supérieur, et l'essai gratuit les inclut. Un bot Custom Webhook, qui répond à vos clients depuis votre propre serveur, demande un forfait payant (Startup ou supérieur). Pour répondre aux clients ou pour attribuer, étiqueter ou résoudre des conversations depuis votre propre code, vous appelez l'API REST, qui demande un forfait Enterprise payant.

Un webhook peut-il modifier quelque chose dans Deskwoot ?

Non. Un webhook ne fait qu'envoyer des événements vers l'extérieur. Pour répondre aux messages des clients depuis votre propre serveur ou depuis n8n, utilisez un bot Custom Webhook sous Paramètres > IA > Autres bots, qui demande un forfait payant (Startup ou supérieur). Pour répondre aux messages des clients, attribuer, étiqueter ou résoudre une conversation ou modifier un contact depuis votre propre code ou depuis n8n, Make ou Zapier, appelez l'API REST, qui demande un forfait Enterprise payant. Chaque conversation à laquelle vous répondez de l'une ou l'autre façon compte comme 1 conversation IA.

À quels événements puis-je m'abonner ?

Conversation créée, Conversation mise à jour, Conversation attribuée, Conversation résolue, Message créé, Contact créé, Contact mis à jour et CSAT envoyé, et, tant que les tickets sont activés, aussi Ticket créé, Ticket mis à jour, Ticket attribué et Ticket résolu. Si aucun événement n'est coché, le webhook reçoit tous les événements sauf ceux des tickets. Les données de chaque événement sont décrites dans la documentation de l'API.

Pourquoi mon webhook ne reçoit-il pas les événements des tickets ?

Un webhook sans événement coché reçoit tout sauf les événements des tickets. Modifiez le webhook et cochez les événements de ticket dont vous avez besoin sous Tickets.

La livraison est-elle signée ?

Oui. Chaque requête porte un en-tête X-Deskwoot-Signature (sha256= suivi du HMAC SHA256 en hexadécimal du corps brut, signé avec le secret de votre webhook) et un en-tête X-Deskwoot-Event avec le nom de l'événement. Le tableau de bord n'affiche pas le secret ; un webhook créé via l'API REST le renvoie une seule fois dans la réponse. Vérifiez la signature avant de traiter une requête, afin de rejeter les requêtes falsifiées.

Deskwoot réessaie-t-il une livraison en échec ?

Une fois. Si la requête échoue, si votre endpoint répond par une erreur ou s'il met plus de 10 secondes, Deskwoot réessaie après 5 secondes. Si cela échoue aussi, l'événement est abandonné, donc prévoyez un endpoint capable de supporter de courtes coupures.

En combien de temps les webhooks sont-ils livrés ?

Au moment même où l'événement se produit, sans file d'attente. Votre endpoint a 10 secondes pour répondre ; une réponse plus lente compte comme une livraison en échec et donne lieu à l'unique nouvelle tentative.

Ai-je besoin de HTTPS ?

Oui. Deskwoot n'envoie qu'à des URL HTTPS publiques et refuse une URL HTTP quand vous enregistrez le webhook, car les payloads contiennent des données clients.

À quoi ressemble la requête ?

Un POST avec Content-Type: application/json. Le corps est un objet JSON avec event, data (les données de l'événement), timestamp et accountId.

Puis-je recevoir le même événement deux fois ?

Rarement, par exemple quand votre endpoint a traité la première requête mais a répondu trop tard, si bien que la nouvelle tentative est arrivée aussi. Le corps ne contient pas d'ID d'événement, utilisez donc le nom de l'événement avec l'ID de l'objet dans data (par exemple l'ID du message) pour ignorer les événements déjà traités.

Puis-je filtrer les événements avant leur envoi ?

Par type d'événement, oui : cochez seulement les événements dont vous avez besoin. Par contenu (par exemple uniquement les conversations d'une boîte de réception), non. Filtrez-les sur votre endpoint.

Que se passe-t-il si mon endpoint est hors service pendant quelques heures ?

Les événements de cette période sont perdus, car Deskwoot ne conserve rien au-delà de l'unique nouvelle tentative. Une fois votre endpoint de retour, vous pouvez rattraper le retard via l'API REST (Enterprise) : listez les conversations triées par activité la plus récente et comparez-les avec vos données.

Puis-je envoyer les événements à plusieurs endpoints ?

Oui. Créez un webhook par URL, chacun avec ses propres événements. C'est utile quand un outil a besoin de tous les événements et un autre de quelques-uns seulement.

Comment tester un webhook avant de le mettre en service ?

Le tableau de bord n'a pas de bouton de test. Faites pointer un webhook vers une URL temporaire d'un service comme webhook.site ou RequestBin, puis créez un vrai événement, par exemple en écrivant à l'une de vos boîtes de réception. Vérifiez les payloads et votre code qui les lit, puis remplacez l'URL par votre vrai endpoint avec Modifier.