Intégration Webhook - Guide complet des déclencheurs HTTP

Intégrez les webhooks Echobell à vos applications : méthodes HTTP, variables, modèles, en-têtes et exemples pratiques pour des notifications instantanées.


Les webhooks sont la façon la plus polyvalente de déclencher des notifications Echobell. Ce guide complet couvre tout ce que vous devez savoir sur l'intégration d'alertes basées sur webhook dans vos systèmes, des concepts de base aux modèles d'utilisation avancés.

Vous utilisiez des clés Direct ? Les clés Direct sont désormais des canaux. Chacune de vos clés a été transformée en canal portant le même nom, et son ancienne URL https://hook.echobell.one/d/… continue de fonctionner exactement comme avant : vos scripts n'ont pas besoin d'être modifiés. Les nouvelles intégrations peuvent utiliser l'URL webhook /t/ du canal, disponible dans l'app, qui accepte les mêmes champs. Sur l'URL /t/, notificationType peut seulement abaisser le niveau auquel vous êtes abonné (voir Niveau de notification) : si un script demande calling, abonnez-vous au canal en mode Appel.

Qu'est-ce qu'un webhook

Un webhook est une façon pour une application de fournir des informations en temps réel à d'autres applications. C'est comme un numéro de téléphone que vous donnez à quelqu'un - quand ils appellent ce numéro, votre téléphone sonne. Dans le monde numérique, quand quelque chose se produit dans un système, il envoie une requête HTTP à une URL (le webhook) que vous avez fournie, déclenchant une action dans votre système.

Par exemple, lorsque l'utilisation du CPU de votre serveur devient trop élevée, votre système de surveillance peut appeler l'URL webhook d'Echobell, qui déclenche alors une notification pour vous alerter. Cela se produit automatiquement et en temps réel, sans que vous ayez à vérifier constamment l'utilisation du CPU vous-même.

Qu'est-ce qu'un endpoint de webhook ?

Un endpoint de webhook est l'URL qui reçoit les requêtes webhook : l'adresse que vous collez dans le service émetteur pour qu'il sache où livrer chaque événement. L'émetteur envoie une requête HTTP (en général un POST avec un corps JSON) à cette URL, et l'endpoint répond avec un code de statut comme 200 OK pour confirmer qu'il a bien reçu l'événement.

Dans Echobell, chaque canal a son propre endpoint de webhook, par exemple https://hook.echobell.one/t/<channel-token>. Collez-le dans Grafana, GitHub Actions, TradingView ou tout autre service comme URL de webhook, et chaque requête qui lui est envoyée devient une notification pour les abonnés du canal. C'est le jeton dans l'URL qui identifie le canal : traitez donc l'endpoint comme un mot de passe.

Vue d'ensemble

Les canaux sont la façon dont Echobell reçoit les webhooks. Chaque canal possède sa propre URL webhook, et lorsque cette URL est appelée, le canal envoie une notification à tous ses abonnés.

Créer un canal ne demande qu'un nom. Par défaut, le canal affiche le title, le body et le externalLink envoyés par chaque requête, tels quels — pratique pour vos propres scripts, tâches cron et étapes de CI. Lorsque la requête provient d'un autre service, vous pouvez activer un modèle personnalisé et construire la notification à partir des données de la requête.

Format d'URL Webhook

https://hook.echobell.one/t/{token-du-canal}

Vous pouvez trouver l'URL webhook de votre canal dans la vue des détails du canal dans l'application Echobell.

Effectuer des requêtes Webhook

Par défaut, un canal lit quatre champs dans chaque requête. Les noms de champs ne sont pas sensibles à la casse (title, Title et TITLE désignent le même champ), et ils peuvent figurer dans la chaîne de requête d'un GET, ou dans un corps POST JSON ou encodé en formulaire.

ChampDescription
titleTitre de la notification. Par défaut, le nom du canal.
bodyCorps de la notification. Vide par défaut.
externalLinkUn lien affiché avec l'enregistrement de la notification. Utile pour pointer vers un tableau de bord, un journal ou une pull request.
notificationTypeactive, time-sensitive ou calling. Ne peut qu'abaisser le niveau choisi par chaque abonné — voir Niveau de notification.

Requête GET

GET https://hook.echobell.one/t/<channel-token>?title=Backup%20finished&body=Nightly%20backup%20completed

Requête POST

Envoyez un corps JSON :

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "title": "CPU alert",
  "body": "Production CPU usage reached 95%",
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Ou un corps encodé en formulaire, ce qu'envoie curl -d :

curl -d "title=Hello&body=World" https://hook.echobell.one/t/<channel-token>

Ouvrir l'URL dans un navigateur

Un GET sans chaîne de requête ni corps — ce qu'envoie un navigateur ou l'aperçu de lien d'une app de chat — ne notifie personne. Le canal répond à la place par une courte description des champs qu'il accepte :

{
  "success": true,
  "notificationTriggered": false,
  "message": "This is an Echobell channel webhook. It pushes a notification to the channel's subscribers. Send a title or a body to trigger one.",
  "usage": { "...": "..." }
}

Ajoutez un title ou un body pour envoyer une notification. Un POST notifie toujours, même avec un corps vide (le titre est alors le nom du canal).

POST uniquement

Chaque canal dispose d'un commutateur POST uniquement dans les Paramètres avancés de l'app Echobell. Il est désactivé par défaut.

Lorsqu'il est activé, seul POST peut déclencher le canal. Une requête GET vers l'URL du webhook est rejetée avec 405 Method Not Allowed, et aucune notification n'est envoyée :

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

Les requêtes HEAD ne sont pas concernées : elles répondent 200 et ne déclenchent jamais de notification, que POST uniquement soit activé ou non.

Activez-le lorsque l'URL du webhook se retrouve dans un endroit qui charge les liens automatiquement — un message de chat, une page de wiki, la barre d'adresse du navigateur — afin qu'un aperçu ou une ouverture de l'URL ne puisse pas déclencher d'alerte. Laissez-le désactivé si l'un de vos appelants déclenche le canal avec GET.

Niveau de notification

Chaque personne qui s'abonne à un canal choisit pour lui un type de notification dans l'app : Normal (active), Urgent ou Appel. Ce choix est le niveau le plus élevé auquel le canal peut la joindre. Une requête peut envoyer notificationType pour demander un niveau inférieur, jamais supérieur.

Par exemple, abonnez-vous à votre canal « Production » en mode Appel. Les requêtes signalant des pannes omettent notificationType et sonnent donc comme un appel téléphonique. Les événements de routine, comme un déploiement terminé, envoient notificationType=active et arrivent comme une notification normale :

curl -d "title=Deploy finished&body=v2.1.0 is live&notificationType=active" \
  https://hook.echobell.one/t/<channel-token>

Un coéquipier abonné au même canal en mode Urgent reçoit la panne comme une notification urgente, jamais comme un appel.

Les canaux dont l'option Modèle personnalisé est activée ignorent notificationType dans la requête : chaque abonné reçoit toujours le niveau qu'il a choisi.

Modèles personnalisés

Par défaut, un canal affiche le title, le body et le externalLink envoyés par chaque requête. Lorsque la requête provient d'un service dont vous ne pouvez pas modifier le payload — un outil de supervision, un système de CI, une boutique —, activez Modèle personnalisé sous Paramètres avancés dans les paramètres du canal, puis rédigez un modèle de titre et un modèle de corps. Le canal construit alors chaque notification à partir de ces modèles, et chaque paramètre de requête et champ JSON de la requête devient une variable.

Passez des variables via des paramètres de requête :

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

Ou dans un corps JSON :

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

Variables de modèle

Utilisez les variables dans vos modèles de notification avec la syntaxe {{nomVariable}} :

Titre : Alerte serveur {{server_name}}
Corps : L'utilisation du CPU a atteint {{cpu_usage}}%

Lorsqu'elles sont déclenchées, ces modèles seront remplis avec les valeurs fournies dans votre requête webhook. Consultez Modèles pour la syntaxe complète et Conditions pour filtrer les requêtes qui notifient.

Variables spéciales

  • externalLink : Lorsqu'incluse dans la requête, cela crée un lien cliquable dans la vue des enregistrements de notification, sauf si le canal possède son propre modèle de lien externe.
POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Variables temporelles système (UTC)

En plus des données que vous envoyez, Echobell fournit des variables temporelles système en lecture seule toujours disponibles dans les modèles et les conditions (UTC). Les champs plats incluent date, time, year, month, dayOfWeek, hour, minute et second. D’autres — comme sys.dayOfWeekName, sys.epochMs et sys.epochSeconds — ne sont disponibles que sous l’espace de noms sys.. Voir Conditions pour la liste complète et des exemples.

Cas d'utilisation courants

Les webhooks sont particulièrement utiles pour :

  • La surveillance et les alertes serveur
  • Les notifications de pipeline CI/CD
  • Les mises à jour d'état des appareils IoT
  • Le suivi des erreurs d'application
  • Les notifications de commandes e-commerce
  • Les alertes système automatisées

Meilleures pratiques

  1. Gestion des erreurs : Echobell répond à chaque appel webhook avec un statut HTTP et un corps JSON. Vérifiez d'abord le statut HTTP, puis notificationTriggered pour savoir si une notification est partie :
    • 200 OK : la requête a été traitée. notificationTriggered: true signifie qu'une notification a été envoyée. notificationTriggered: false signifie que rien n'a été envoyé volontairement : les conditions du canal ne correspondaient pas (conditionsMet: false), ou un GET vide a reçu la description d'utilisation.
    • 400 Bad Request : le jeton dans l'URL n'a pas la bonne longueur.
    • 404 Not Found : aucun canal n'a ce jeton (code: "TRIGGER_TOKEN_NOT_FOUND" ; sur une ancienne URL /d/, DIRECT_KEY_NOT_FOUND). Le canal a été supprimé ou son URL webhook réinitialisée.
    • 405 Method Not Allowed : POST uniquement est activé et la requête n'était pas un POST.
    • 413 Payload Too Large : le corps de la requête dépasse 1 Mio.
    • 429 Too Many Requests : plus de 120 requêtes en une minute pour la même URL webhook. La réponse contient un en-tête Retry-After (en secondes) ; attendez ce délai avant de réessayer.
    • 500 : problème temporaire du serveur, réessayez avec un backoff exponentiel.
  2. Limitation de débit : Implémentez des délais raisonnables entre les appels webhook pour éviter de surcharger votre système de notifications. Chaque URL webhook accepte jusqu'à 120 requêtes par minute ; au-delà, Echobell répond 429.
  3. Sécurité des données : Ne partagez les URLs webhook qu'avec des systèmes et services de confiance
  4. Tests : Testez votre intégration webhook avec des données minimales avant de l'implémenter en production

Confidentialité et sécurité

Rappelez-vous que :

  • Les URLs webhook doivent être traitées comme des secrets
  • N'envoyez que les données nécessaires dans les requêtes webhook
  • Tout le contenu des notifications est stocké localement sur les appareils des abonnés
  • Nos serveurs ne font que traiter la requête webhook et router les notifications

Dépannage

Si vos webhooks ne fonctionnent pas comme prévu :

  1. Vérifiez que l'URL webhook est correcte
  2. Vérifiez si le canal est actif
  3. Assurez-vous que votre payload JSON est correctement formaté (pour les requêtes POST)
  4. Confirmez que toutes les variables requises dans vos modèles sont fournies (canaux avec modèle personnalisé)
  5. Vérifiez si le canal a des abonnés actifs

Besoin d'aide ? Visitez notre Centre de support ou contactez-nous à echobell@weelone.com.