---
title: Intégration Webhook - Guide complet des déclencheurs HTTP
sidebarTitle: Webhooks
description: "Intégrez les webhooks Echobell à vos applications : méthodes HTTP, variables, modèles, en-têtes et exemples pratiques pour des notifications instantanées."
---

# Intégration Webhook

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.

<Callout type="info">
  **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](#niveau-de-notification)) : si un script demande
  `calling`, abonnez-vous au canal en mode Appel.
</Callout>

## 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é](#modèles-personnalisés) 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.

| Champ | Description |
|---|---|
| `title` | Titre de la notification. Par défaut, le nom du canal. |
| `body` | Corps de la notification. Vide par défaut. |
| `externalLink` | Un lien affiché avec l'enregistrement de la notification. Utile pour pointer vers un tableau de bord, un journal ou une pull request. |
| `notificationType` | `active`, `time-sensitive` ou `calling`. Ne peut qu'abaisser le niveau choisi par chaque abonné — voir [Niveau de notification](#niveau-de-notification). |

### Requête GET

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

### Requête POST

Envoyez un corps JSON :

```http
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` :

```bash
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 :

```json
{
  "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 :

```json
{
  "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](/fr/docs/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 :

```bash
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 :

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

Ou dans un corps JSON :

```http
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](/fr/docs/template) pour la syntaxe complète et [Conditions](/fr/docs/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.

```http
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](/fr/docs/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](#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](/fr/docs/support) ou contactez-nous à echobell@weelone.com.
