Utilisez ce guide pour envoyer les erreurs d'intégration de Fin à vos propres systèmes en temps réel. Lorsque vous ajoutez un webhook, Fin envoie une requête POST signée à votre URL à chaque nouvelle erreur apparaissant dans les journaux d'erreurs, afin que vous puissiez la diriger vers votre système d'alerte, de ticketing ou de surveillance.
Note : Les webhooks des journaux d'erreurs sont disponibles pour Fin pour les espaces de travail plateformes connectés à Salesforce, HubSpot, Freshdesk ou Zendesk.
Avant de commencer
Vous avez besoin de la permission Gérer les applications et intégrations pour ajouter, tester ou supprimer le webhook. Sans cela, vous pouvez sélectionner Demander la permission dans le panneau Webhook.
Votre point de terminaison doit être accessible publiquement via HTTPS. Lors de l'enregistrement, Fin envoie une requête HEAD pour vérifier son accessibilité.
Votre point de terminaison doit renvoyer un code d'état 2xx en moins de 7 secondes.
Comment ajouter un webhook
Allez dans Paramètres > Journaux d'erreurs (sous Intégrations).
Cliquez sur Webhook en haut à droite de la page.
Dans URL du webhook, saisissez votre point de terminaison, par exemple
your-server.example.com/error-logs. Le préfixehttps://est ajouté automatiquement.Sélectionnez Enregistrer. Vous verrez « Webhook enregistré » lorsque l'URL sera validée.
(Optionnel) Copiez le Secret de signature affiché sous l'URL. Vous l'utiliserez pour vérifier que les requêtes proviennent de Fin.
Sélectionnez Tester pour envoyer un événement test à votre point de terminaison. Vous verrez « Test envoyé » si votre point de terminaison répond avec succès.
Note : Le test envoie un événement
ping, pas un journal d'erreur. Assurez-vous que votre point de terminaison accepte les deux sujets (voir les exemples ci-dessous).
Ce que Fin envoie à votre webhook
Fin envoie une requête pour chaque nouvelle erreur apparaissant dans les journaux d'erreurs. Si la même erreur se répète pour la même conversation dans l'heure, elle peut n'être enregistrée et envoyée qu'une seule fois.
Chaque requête est un POST avec un corps JSON et ces en-têtes :
Content-Type : application/json
X-Hub-Signature : la signature de la requête (voir Comment vérifier la signature).
Intercom-Webhook-Subscription-ID : l'ID de votre abonnement webhook.
Exemple de charge utile de journal d'erreur
Les détails de l'erreur sont dans data.item. Le sujet est toujours error_log.created.
{
"type": "notification_event",
"app_id": "abc123de",
"topic": "error_log.created",
"id": "notif_1a2b3c4d",
"created_at": 1762430400,
"data": {
"type": "notification_event_data",
"item": {
"type": "error_log",
"id": "123",
"app_id": "abc123de",
"created_at": 1762430400,
"environment": {
"type": "environment",
"id": "456",
"name": "acme.my.salesforce.com",
"is_production": true
},
"error_code": "INVALID_FIELD",
"error_message": "No such column 'InvalidField' on entity 'Case'",
"request_status": 400,
"request_method": "POST",
"request_path": "/services/data/v58.0/sobjects/Case",
"object_type": "Case",
"api_type": "salesforce_rest_api",
"product_feature": "salesforce_cases",
"integration_type": "salesforce_cases",
"conversation_id": "789"
}
}
}
Champs du journal d'erreur
id : l'ID de l'entrée du journal d'erreur.
app_id : l'ID de votre espace de travail Fin.
created_at : moment où l'erreur s'est produite, sous forme de timestamp Unix en secondes.
environment : l'environnement helpdesk connecté, comme votre organisation Salesforce ou sous-domaine Zendesk. Peut être nul.
error_code : le code d'erreur retourné par votre helpdesk, par exemple INVALID_FIELD.
error_message : le message d'erreur retourné par votre helpdesk.
request_status, request_method et request_path : le statut HTTP, la méthode et le chemin de la requête qui a échoué.
object_type : l'objet helpdesk concerné, par exemple Case ou Knowledge__kav.
api_type : l'API helpdesk appelée par Fin, par exemple salesforce_rest_api, hubspot_rest_api, freshdesk_rest_api ou zendesk_rest_api.
product_feature : la fonctionnalité Fin affectée, par exemple salesforce_cases, fin_messenger, knowledge_import ou historical_conversations_import.
integration_type : l'intégration Fin d'où provient l'erreur, par exemple salesforce_cases ou zendesk_tickets.
conversation_id : la conversation Fin associée, s'il y en a une. Peut être nul.
Note : Ces champs correspondent à ce que vous voyez dans le panneau Détails de l'erreur dans les journaux d'erreurs. Pour comprendre et corriger un code d'erreur spécifique, consultez Fin for Salesforce : Corriger les erreurs d'intégration courantes.
Important : error_message et request_path proviennent directement de votre helpdesk et peuvent inclure des données d'enregistrement, telles que des valeurs de champs ou des IDs. Stockez les charges utiles en toute sécurité.
Exemple de charge utile de test
{
"type": "notification_event",
"topic": "ping",
"data": {
"type": "notification_event_data",
"item": {
"type": "ping",
"message": "This is a ping notification test message."
}
}
}
Comment vérifier la signature
Chaque requête inclut un en-tête X-Hub-Signature. C'est un HMAC-SHA1 du corps brut de la requête, signé avec votre secret de signature, au format sha1=<digest hexadécimal>.
Pour vérifier une requête :
Calculez un HMAC-SHA1 du corps brut de la requête, avant de parser le JSON, en utilisant votre secret de signature comme clé.
Préfixez le digest hexadécimal avec sha1=.
Comparez-le avec l'en-tête X-Hub-Signature en utilisant une comparaison en temps constant. Rejetez la requête si elles ne correspondent pas.
Par exemple, en Ruby :
expected = "sha1=" + OpenSSL::HMAC.hexdigest("SHA1", signing_secret, raw_body)
valid = Rack::Utils.secure_compare(expected, request.headers["X-Hub-Signature"])Important : Gardez votre secret de signature privé. Le fait de le voir ou de le copier est enregistré dans le journal d'activité des coéquipiers de votre espace de travail.
Livraison et nouvelles tentatives
Une livraison est considérée réussie lorsque votre point de terminaison renvoie un code d'état 2xx. Fin ne suit pas les redirections, utilisez donc l'URL finale de votre point de terminaison.
Si votre point de terminaison expire ou renvoie une erreur, Fin réessaie automatiquement la livraison.
Si votre point de terminaison renvoie 410 Gone, Fin arrête immédiatement l'envoi vers celui-ci.
Fin peut envoyer plusieurs fois le même événement. Utilisez l'id de niveau supérieur de l'événement pour ignorer les doublons.
Fin peut livrer les événements dans le désordre. Utilisez created_at pour les trier.
Fin envoie une requête par erreur, donc une panne dans votre helpdesk peut envoyer de nombreuses requêtes en peu de temps. Répondez rapidement et traitez les événements en arrière-plan.
Messages d'état du webhook
Si les livraisons échouent, le panneau Webhook affiche un de ces messages :
En pause : « Votre point de terminaison renvoie des erreurs, donc les livraisons sont en pause. Nous réessaierons automatiquement. » Aucune action n'est nécessaire si le problème est temporaire.
Suspendu : « Votre point de terminaison a continué à renvoyer des erreurs, donc les livraisons sont suspendues. » Corrigez votre point de terminaison, puis sélectionnez Enregistrer à nouveau pour reconnecter.
Désactivé : « Votre point de terminaison a renvoyé 410 Gone, donc les livraisons ont été arrêtées. » Sélectionnez Enregistrer à nouveau pour reconnecter.
Arrêté par Fin : « Fin a arrêté les livraisons vers ce webhook. » Contactez le support pour les reprendre.
Comment supprimer un webhook
Allez dans Paramètres > Journaux d'erreurs et sélectionnez Webhook.
Sélectionnez l'icône de la corbeille à côté de l'URL.
Sélectionnez Supprimer le webhook pour confirmer.
Fin arrête d'envoyer de nouveaux journaux d'erreurs à cette URL. Ceux déjà en cours peuvent encore arriver. Vous pouvez ajouter un webhook à tout moment. Si vous le faites, un nouveau secret de signature est créé, pensez à le mettre à jour dans votre point de terminaison.
FAQ
Puis-je envoyer les journaux d'erreurs à plusieurs URL ?
Puis-je envoyer les journaux d'erreurs à plusieurs URL ?
Pas encore. Chaque espace de travail peut avoir un seul webhook pour les journaux d'erreurs.
Puis-je choisir quelles erreurs sont envoyées ?
Puis-je choisir quelles erreurs sont envoyées ?
Non. Fin envoie chaque nouvelle erreur apparaissant dans les journaux d'erreurs. Vous pouvez filtrer sur des champs comme product_feature, api_type ou error_code dans votre propre système.
Est-ce que Fin envoie les erreurs passées lorsque j'ajoute un webhook ?
Est-ce que Fin envoie les erreurs passées lorsque j'ajoute un webhook ?
Non. Seules les erreurs enregistrées après l'enregistrement du webhook sont envoyées.
Pourquoi le test n'a-t-il pas envoyé de journal d'erreur ?
Pourquoi le test n'a-t-il pas envoyé de journal d'erreur ?
Le bouton Tester envoie un événement ping pour vérifier que votre point de terminaison est accessible. Les vrais journaux d'erreurs utilisent le sujet error_log.created.
Puis-je changer ou régénérer le secret de signature ?
Puis-je changer ou régénérer le secret de signature ?
Le secret reste le même tant que le webhook est configuré. Pour obtenir un nouveau secret, supprimez le webhook puis ajoutez-le à nouveau.

