Aperçu
Fonctionnement des webhooks
- Configurer l’URL du webhook et sélectionner les types d’événements
- Quo surveille les événements spécifiés
- Quand l’événement se produit, Quo envoie une requête POST avec la charge utile de l’événement
- Votre application traite les données de l’événement et répond
- Quo consigne l’état de la remise et effectue une relance au besoin
La configuration des webhooks nécessite des autorisations de propriétaire ou d’administrateur de l’espace de travail. Les paramètres se gèrent uniquement dans les applications Web et de bureau.

Événements de webhook disponibles
Événements de messagerie
message.received: SMS reçu par le numéro de téléphone de l’espace de travail (incluant les pièces jointes)message.delivered: SMS envoyé depuis l’espace de travail et livré avec succès (incluant des médias)
call.summary.completed: Résumé d’appel généré par l’IA disponible dans la charge utile de l’événementcall.transcript.completed: Transcription complète de l’appel disponible dans la charge utile de l’événement
Événements vocaux
call.ringing: Appel entrant reçu par le numéro de téléphone de l’espace de travailcall.completed: Appel terminé (répondu ou non, peut inclure une boîte vocale)call.recording.completed: Enregistrement de l’appel disponible à l’URL fournie
Événements de contacts
Gestion des contacts :contact.updated: Contact créé ou modifié dans l’espace de travailcontact.deleted: Contact supprimé de l’espace de travail
Événements de tâche
task.created: Tâche créée dans votre espace de travailtask.updated: Le titre, la description, la personne assignée ou la date d’échéance de la tâche ont été modifiéstask.completed: Tâche marquée comme terminéetask.reopened: Tâche terminée rouvertetask.deleted: Tâche supprimée de votre espace de travailtask.unassigned: La tâche n’est plus assignée à personnetask.due_date_changed: La date d’échéance de la tâche a été modifiéetask.due_date_removed: La date d’échéance de la tâche a été suppriméetask.overdue: La tâche a dépassé sa date d’échéancetask.linked: Tâche associée à une conversation, à un numéro de téléphone ou à une activité dans une conversationtask.unlinked: Tâche dissociée d’une conversation
Pour en savoir plus sur l’utilisation des webhooks et de l’API, consultez la référence de l’API Quo.
Configuration des webhooks
Exigences de configuration
Paramètres facultatifs :
Processus de configuration
- Accédez à Settings → Webhooks dans Quo
- Cliquez sur Create webhook
- Saisissez l’URL de votre gestionnaire de webhook
- Sélectionnez les types d’événements à surveiller
- Choisissez les numéros de téléphone ou les ressources de contacts
- Ajoutez une étiquette facultative pour l’identification
- Enregistrez et testez la configuration
Créer des gestionnaires de webhooks
Exigences du gestionnaire
- Accepter les requêtes HTTP POST à votre URL de webhook
- Traiter la charge utile d’événement JSON dans le corps de la requête
- Répondre avec un code d’état HTTP 2xx dans les 10 secondes
- Vérifier la signature du webhook pour des raisons de sécurité
- Gérer les relances et les échecs de manière robuste
- Succès : Renvoyer un code d’état 2xx (aucun corps de réponse requis)
- Échec : Une réponse non 2xx déclenche la séquence de relance de Quo
- Expiration : Aucune réponse dans les 10 secondes entraîne des relances
Sécurité et authentification
Processus de vérification de la signature
- Extraire les composantes de l’en-tête
openphone-signature - Préparer les données à signer en concaténant
timestamp + "." + payload - Décoder la clé de signature à partir de base64 (disponible dans les détails du webhook)
- Calculer HMAC-SHA256 avec la clé décodée et les données à signer
- Comparer le résultat avec la signature dans l’en-tête
- Supprimer tous les espaces et retours de ligne de la charge utile JSON avant la concaténation
- Utiliser la forme binaire de la clé décodée de base64 pour le calcul HMAC
- Assurer une correspondance exacte des chaînes pour que la vérification réussisse
- Accédez à la page des détails du webhook dans Quo
- Cliquez sur l’icône des points de suspension (⋯) en haut à droite
- Sélectionnez « Révéler le secret de signature »
- Copiez la clé encodée en base64 pour votre application
Exemples d’implémentation
Les versions futures pourraient inclure plusieurs signatures séparées par des virgules. Divisez la valeur de l’en-tête selon les virgules pour gérer plusieurs signatures au besoin.
Bonnes pratiques de sécurité
- Comparez l’horodatage de la signature à l’heure actuelle
- Rejetez les requêtes dont l’horodatage est hors de la plage de tolérance acceptée (p. ex., 5 minutes)
- Chaque appel de webhook génère un horodatage et une signature uniques
- Les relances incluent automatiquement de nouveaux horodatages
- Utilisez toujours des URL HTTPS pour les webhooks de production
- Stockez les clés de signature de manière sécurisée (variables d’environnement, gestion des secrets)
- Mettez en place une gestion adéquate des erreurs et la journalisation
- Envisagez de limiter le taux de requêtes pour les points de terminaison de webhook
Gestion des erreurs et relances
Système de relance automatique
- Conditions de déclenchement : codes de réponse autres que 2xx ou délai d’expiration de 10 secondes
- Stratégie d’attente : délai exponentiel avec intervalles croissants
- Durée des relances : jusqu’à 3 jours de tentatives de relance
- Échec final : notification par courriel envoyée au créateur du webhook
- Les premières tentatives ont lieu rapidement afin de réduire le délai au minimum
- Les délais augmentent de façon exponentielle à chaque tentative
- Priorise la livraison le plus près possible de l’heure de l’événement d’origine
- Suivi automatique de l’état tout au long du processus
Options de nouvelle tentative manuelle
- Voir l’état de livraison dans les détails du webhook Quo
- Relancer manuellement les appels webhook ayant échoué en tout temps
- Les webhooks en échec sont marqués avec l’état « failure »
- Les relances manuelles réussies mettent à jour l’état à « success »
Notifications d’échec
- Alerte par courriel envoyée au créateur du webhook
- Appel de webhook marqué comme échec permanent
- Détails de l’événement conservés pour examen manuel
- Possibilité de relancer manuellement une fois les problèmes résolus
Tests et validation
Tests de développement
- Clients HTTP : Utilisez cURL, Postman ou Insomnia pour envoyer des requêtes POST de test
- URL locales : Testez avec localhost durant le développement
- Charges utiles simulées : Créez des exemples d’événements JSON conformes au format Quo
- Tests de signature : Vérifiez la logique de validation HMAC avec des clés de test
Fonctionnalités de test de Quo
- Accédez à la page des détails du webhook dans Quo
- Cliquez sur les points de suspension (⋯) en haut à droite
- Sélectionnez « Envoyer une requête de test »
- Quo envoie un événement d’exemple à l’URL de votre webhook
- Vérifiez la validation de la signature et le traitement de la réponse
Les requêtes de test nécessitent des URL de webhook accessibles publiquement. Les URL de développement local ne fonctionnent pas avec la fonctionnalité de test de Quo.
Tests d’événements en direct
- Configurez le webhook pour un type d’événement précis (p. ex.,
message.received) - Sélectionnez votre numéro Quo dans les ressources du webhook
- Déclenchez un événement réel (envoyez un message texte à votre numéro)
- Surveillez l’envoi du webhook et son traitement
- Vérifiez le bon fonctionnement de bout en bout
- Le webhook reçoit correctement les requêtes POST
- La vérification de la signature fonctionne
- L’analyse de la charge utile de l’événement réussit
- La logique de l’application traite correctement les événements
- Les réponses d’erreur déclenchent des relances
- Les réponses indiquant un succès mettent fin à la séquence de relance
Résolution des problèmes
Problèmes courants et solutions
- Vérifiez que l’URL du webhook est correcte et accessible
- Vérifiez que l’état du webhook est activé dans les paramètres
- Confirmez que les types d’événements sont correctement sélectionnés
- Vérifiez que les ressources (numéros de téléphone/utilisateurs/groupes) sont correctes
- Codes d’état HTTP : assurez-vous de renvoyer des réponses 2xx pour un traitement réussi
- Délai de réponse : renvoyez les réponses dans un délai maximal de 10 secondes
- Gestion des erreurs : mettez en place des réponses d’erreur appropriées pour faciliter le débogage
- Vérification de la signature : vérifiez le calcul de la signature HMAC
- Format de la clé : assurez-vous que la clé de signature est correctement décodée en Base64
- Gestion de l’horodatage : vérifiez l’extraction et la concaténation de l’horodatage
Outils de débogage
- Journal des événements : Consultez l’historique de livraison dans la page de détails du webhook
- Suivi de l’état : Surveillez les taux de réussite et d’échec
- Tentatives de reprise : Passez en revue les séquences de reprise automatiques
- Tests manuels : Utilisez “Send Test Request” pour une validation immédiate
- Temps de réponse : Gardez le temps de traitement sous les 10 secondes
- Taux d’erreur : Réduisez les échecs au minimum pour limiter la charge liée aux nouvelles tentatives
- Journalisation : Mettez en place une journalisation complète des requêtes et des réponses
- Surveillance : Configurez des alertes en cas d’échec de livraison du webhook
Exemples de charges utiles d’événement
Événements de messages
message.received :
Événements d’appels
call.ringing :
call.completed (appel entrant avec messagerie vocale) :
call.completed (appel sortant répondu) :
Événements de contact
contact.updated et contact.deleted :
Événements d’analyse IA
call.summary.completed :
call.transcript.completed payload :
