Home Assistant : connecter un webhook Discord

Dans cet article, nous allons voir comment relier un webhook Discord à notre instance Home Assistant. De cette façon, on pourra utiliser cette solution comme outil pour s'envoyer des notifications.

Prérequis

Pour suivre ce tutoriel, vous aurez besoin de :

Serveur Discord avec droit de création de webhook
Home Assistant (Core / OS / Supervised)
Accès à la modification des fichiers configuration.yaml et secrets.yaml

I. Création du webhook Discord

Dans un premier temps, on crée le webhook côté Discord. Il suffit de suivre le chemin ci-dessous, ou de regarder la vidéo.

Création d'un webhook Discord

Étapes de création

Discord → ouvrir le serveur
Paramètres du serveur
Intégrations → Webhooks
Nouveau webhook
Choisir le salon, copier l'URL du webhook

⚠️ Important — Le salon choisi ici sera le seul où le webhook écrira. Pour changer de salon, il faut copier la nouvelle URL. L'URL est l'équivalent d'une clé : à ne pas divulguer.

II. Mettre l'URL dans secrets.yaml

On place ensuite l'URL dans secrets.yaml pour la séparer de la config publique. Très important : aucune info sensible dans configuration.yaml.

Accéder au fichier secrets.yaml

Pour accéder au fichier secrets.yaml, on peut soit y accéder directement depuis la VM, soit depuis l'interface web HA en installant l'add-on File Editor.

Installation du module File Editor

Une fois cela fait, on accède directement au fichier secrets.yaml :

Accès au fichier secrets.yaml

Configuration du secret

Une fois dedans, ajouter :

secrets.yaml YAML

discord_webhook_url: "URL_WEBHOOK"

Remplacer URL_WEBHOOK par l'URL copiée depuis Discord.

III. Créer la commande HTTP (rest_command)

On crée maintenant la commande rest_command. De la même façon qu'on a ouvert secrets.yaml, il faut ouvrir /config/configuration.yaml.

Ajouter le code suivant :

configuration.yaml YAML

rest_command:
  discord_notify:
    url: !secret discord_webhook_url
    method: POST
    content_type: "application/json"
    payload: '{"content": {{ message | tojson }} }'

Ajout du rest_command dans configuration.yaml — Ajout du `rest_command` dans configuration.yaml

Explication ligne par ligne

rest_command: — déclare une section qui permet à Home Assistant d'envoyer des requêtes HTTP (GET / POST…).

discord_notify: — le nom de votre commande. Ça crée un service appelable via rest_command.discord_notify.

url: !secret discord_webhook_url — l'URL du webhook est récupérée depuis secrets.yaml (plus sécurisé).

method: POST — Discord attend une requête POST pour recevoir un message.

content_type: "application/json" — on envoie un corps au format JSON (ce que Discord attend).

payload: '{"content": {{ message | tojson }} }' — le contenu envoyé à Discord :

content : le texte du message Discord
message : la variable passée au moment de l'appel
tojson : évite de casser le JSON si le texte contient des guillemets, des retours à la ligne, ou des caractères spéciaux

💡 Pourquoi tojson ? Sans tojson, certains messages peuvent faire planter l'envoi avec une erreur « invalid JSON ».

IV. Vérifier la config et redémarrer Home Assistant

Après modification de configuration.yaml, il faut maintenant vérifier la syntaxe et sauvegarder :

Vérification et sauvegarde — Vérification et redémarrage de Home Assistant

Étapes de vérification

Outils développeur
Vérifier la config
Redémarrer

⚠️ Important — Sans redémarrage, Home Assistant ne charge pas le nouveau rest_command, donc rest_command.discord_notify n'apparaîtra pas.

V. Tester l'envoi (depuis l'UI)

On passe maintenant au test. Aller dans :

Outils de développement → Actions (ou Services selon la version).

Choisir :

Action / Service : rest_command.discord_notify

Sélection du service rest_command.discord_notify — Sélection du service `rest_command.discord_notify`

Données du test

Puis renseigner les données suivantes :

action YAML

action: rest_command.discord_notify
data:
  message: "Test webhook OK depuis Home Assistant by Ryan"

Résultat

Si tout fonctionne, le message arrive dans le salon Discord :

Conclusion

Avec cette configuration, on peut envoyer des notifications depuis Home Assistant vers Discord. Très pratique pour :

Recevoir des alertes de sécurité
Être notifié quand quelqu'un sonne à la porte
Suivre l'état des appareils connectés
Créer des automatisations personnalisées

🚀 Prochaines étapes — créer des automatisations qui envoient des messages automatiquement, personnaliser avec des embeds Discord, ajouter des mentions ou des rôles, intégrer d'autres canaux (Telegram, email, etc.).