🔗 Webhook — Liens d'action externe
Générez des URLs signées qui déclenchent des commandes de votre bot depuis n'importe quel navigateur web, email, ou service externe
Introduction
La bibliothèque Webhook permet de créer des URLs sécurisées qui, lorsqu'elles sont visitées (GET) ou appelées (POST), déclenchent automatiquement une commande sur votre bot Telegram.
🎯 Cas d'utilisation typiques
- Confirmation email — Un lien dans un email qui valide l'inscription de l'utilisateur
- Boutons de paiement — Un service de paiement appelle votre bot après un achat réussi
- Pages web interactives — Des boutons sur votre site qui déclenchent des actions dans Telegram
- IoT / Automatisation — Un capteur ou un service tiers envoie des données à votre bot
- Redirection intelligente — Un lien qui enregistre un clic puis redirige l'utilisateur vers un site
Comment ça marche ?
Installation
Avant d'utiliser Webhook dans votre code, installez la bibliothèque depuis l'application :
- Ouvrez votre bot dans BotStrike
- Allez dans l'onglet Bibliothèques (📚)
- Trouvez Webhook dans la liste
- Appuyez sur Installer
Webhook sans l'avoir installé, une erreur explicite sera levée :
❌ Webhook BotStrike n'est pas installée. Allez dans Bibliothèques → Webhook → Installer pour l'activer.
Générer une URL webhook
Utilisez Webhook.getUrlFor() (JS) ou Webhook.get_url_for() (PY) pour créer un lien signé.
Syntaxe
| Paramètre | Type | Requis | Description |
|---|---|---|---|
command | string | ✅ Oui | Nom de la commande à déclencher (ex: "confirm", "/validate") |
user_id | string/number | ❌ Non | ID Telegram de l'utilisateur cible. Par défaut : utilisateur courant |
content | string | ❌ Non | Données à transmettre à la commande (récupérables via la variable content) |
redirect_to | string | ❌ Non | URL vers laquelle rediriger l'utilisateur après le déclenchement |
Exemple minimal
// Générer un lien qui déclenche /confirm
const url = Webhook.getUrlFor({ command: "confirm" });
bot.send("Cliquez ici pour confirmer : " + url);
# Générer un lien qui déclenche /confirm
url = Webhook.get_url_for({"command": "confirm"})
bot.send("Cliquez ici pour confirmer : " + url)
Exemple avec toutes les options
const url = Webhook.getUrlFor({
command: "payment_done",
user_id: user.id,
content: "order_12345",
redirect_to: "https://monsite.com/merci"
});
// → https://hook.botstrike.net/wh/eyJ1aC...Ig.a3b2f1...
url = Webhook.get_url_for({
"command": "payment_done",
"user_id": user["id"],
"content": "order_12345",
"redirect_to": "https://monsite.com/merci"
})
# → https://hook.botstrike.net/wh/eyJ1aC...Ig.a3b2f1...
/ au début du nom de commande est optionnel : "confirm" et "/confirm" déclenchent tous deux /confirm.
Recevoir un webhook
Quand un utilisateur clique sur l'URL ou qu'un service l'appelle, votre commande s'exécute normalement, comme si l'utilisateur avait tapé la commande dans Telegram.
Méthodes HTTP supportées
| Méthode | Comportement |
|---|---|
GET | Déclenche la commande. Si redirect_to est défini, redirige le navigateur après exécution. |
POST | Déclenche la commande. Le corps de la requête (body) est accessible via la variable content. |
Exemple : commande de confirmation
// Fichier : _confirm.js
// Déclenché quand quelqu'un visite l'URL webhook
if (content) {
bot.send("✅ Confirmation reçue avec données : " + content);
} else {
bot.send("✅ Votre email a été confirmé !");
}
# Fichier : _confirm.py
# Déclenché quand quelqu'un visite l'URL webhook
if content:
bot.send("✅ Confirmation reçue avec données : " + content)
else:
bot.send("✅ Votre email a été confirmé !")
options pour détecter un appel webhook (elle contiendra url, method, etc.).
Variables disponibles
Quand une commande est déclenchée par un webhook, deux variables supplémentaires sont automatiquement peuplées :
content
Contient les données transmises au webhook :
- Si POST — le corps (body) de la requête HTTP
- Si GET avec
contentdéfini — la valeur passée àgetUrlFor({ content: "..." }) - Sinon —
null
options
Dictionnaire contenant les métadonnées de la requête HTTP :
| Clé | Type | Description |
|---|---|---|
url | string | URL complète qui a été visitée |
method | string | "GET" ou "POST" |
params | dict | Paramètres de l'URL (query string) |
headers | dict | En-têtes de la requête HTTP |
ip | string | Adresse IP du visiteur |
Détecter un appel webhook
// Fichier : _start.js
if (options.url) {
// Déclenché via webhook
bot.send("Appel webhook depuis " + options.ip);
} else {
// Déclenché normalement via Telegram
bot.send("Bienvenue !");
}
# Fichier : _start.py
if options.get("url"):
# Déclenché via webhook
bot.send("Appel webhook depuis " + options["ip"])
else:
# Déclenché normalement via Telegram
bot.send("Bienvenue !")
Options avancées
Redirection automatique
Si vous définissez redirect_to, le navigateur de l'utilisateur sera automatiquement redirigé vers cette URL après que la commande s'est exécutée.
// Lien de tracking : enregistre le clic puis redirige
const url = Webhook.getUrlFor({
command: "track_click",
user_id: user.id,
content: "campagne_ete_2025",
redirect_to: "https://monsite.com/promo"
});
# Lien de tracking : enregistre le clic puis redirige
url = Webhook.get_url_for({
"command": "track_click",
"user_id": user["id"],
"content": "campagne_ete_2025",
"redirect_to": "https://monsite.com/promo"
})
Données POST
Quand un service externe envoie un POST à votre URL webhook, le corps de la requête est automatiquement disponible dans la variable content.
// Fichier : _payment_callback.js
// Un service de paiement envoie un POST avec le résultat
const data = JSON.parse(content);
if (data.status === "success") {
bot.send("💰 Paiement reçu : " + data.amount + "€");
Props.set("premium", true);
}
# Fichier : _payment_callback.py
# Un service de paiement envoie un POST avec le résultat
data = json.loads(content)
if data["status"] == "success":
bot.send("💰 Paiement reçu : " + data["amount"] + "€")
Props.set("premium", True)
Sécurité
�️ Sécurité automatique
- URLs sécurisées — Chaque URL est unique et protégée, impossible à deviner ou modifier
- Vérification d'installation — La bibliothèque Webhook doit être installée pour que l'URL fonctionne
- Rate limiting — Protection contre les abus automatique
Webhook.getUrlFor() qui gère la sécurité automatiquement.
Exemples complets
Exemple 1 : Système de confirmation email
Scénario : L'utilisateur donne son email, le bot génère un lien de confirmation à envoyer par email.
// _register.js — l'utilisateur envoie son email
const email = params;
Props.set("email", email);
Props.set("confirmed", false);
const confirmUrl = Webhook.getUrlFor({
command: "confirm_email",
user_id: user.id,
content: email,
redirect_to: "https://monsite.com/bienvenue"
});
bot.send("📧 Envoyez ce lien à " + email + " :\n\n" + confirmUrl);
// _confirm_email.js — déclenché par le clic sur le lien
if (content) {
Props.set("confirmed", true);
bot.send("✅ Email " + content + " confirmé !");
}
# _register.py — l'utilisateur envoie son email
email = params
Props.set("email", email)
Props.set("confirmed", False)
confirm_url = Webhook.get_url_for({
"command": "confirm_email",
"user_id": user["id"],
"content": email,
"redirect_to": "https://monsite.com/bienvenue"
})
bot.send("📧 Envoyez ce lien à " + email + " :\n\n" + confirm_url)
# _confirm_email.py — déclenché par le clic sur le lien
if content:
Props.set("confirmed", True)
bot.send("✅ Email " + content + " confirmé !")
Exemple 2 : Boutons sur une page web
Scénario : Votre site web a des boutons qui déclenchent des actions dans Telegram.
// _generate_links.js — le bot envoie les liens pour le site
const like = Webhook.getUrlFor({ command: "vote", content: "like" });
const dislike = Webhook.getUrlFor({ command: "vote", content: "dislike" });
bot.send("Intégrez ces liens dans votre page web :");
bot.send("👍 Like : " + like);
bot.send("👎 Dislike : " + dislike);
// _vote.js — traitement du vote
const vote = content;
const current = Props.get("votes_" + vote) || 0;
Props.set("votes_" + vote, current + 1);
bot.send("Vote " + vote + " enregistré ! Total : " + (current + 1));
# _generate_links.py — le bot envoie les liens pour le site
like = Webhook.get_url_for({"command": "vote", "content": "like"})
dislike = Webhook.get_url_for({"command": "vote", "content": "dislike"})
bot.send("Intégrez ces liens dans votre page web :")
bot.send("👍 Like : " + like)
bot.send("👎 Dislike : " + dislike)
# _vote.py — traitement du vote
vote = content
current = Props.get("votes_" + vote) or 0
Props.set("votes_" + vote, current + 1)
bot.send("Vote " + vote + " enregistré ! Total : " + str(current + 1))
Exemple 3 : Notification IoT
Scénario : Un capteur de température envoie une alerte au bot via POST.
// _setup_sensor.js — génère l'URL pour le capteur
const sensorUrl = Webhook.getUrlFor({
command: "sensor_alert",
user_id: user.id
});
bot.send("Configurez votre capteur avec cette URL :\n" + sensorUrl);
bot.send("Il peut envoyer un POST avec le JSON de ses données.");
// _sensor_alert.js — reçoit les données du capteur
const data = JSON.parse(content);
if (data.temperature > 35) {
bot.send("🔥 ALERTE : Température = " + data.temperature + "°C !");
} else {
bot.send("🌡️ Capteur OK : " + data.temperature + "°C");
}
# _setup_sensor.py — génère l'URL pour le capteur
sensor_url = Webhook.get_url_for({
"command": "sensor_alert",
"user_id": user["id"]
})
bot.send("Configurez votre capteur avec cette URL :\n" + sensor_url)
bot.send("Il peut envoyer un POST avec le JSON de ses données.")
# _sensor_alert.py — reçoit les données du capteur
data = json.loads(content)
if data["temperature"] > 35:
bot.send("🔥 ALERTE : Température = " + str(data["temperature"]) + "°C !")
else:
bot.send("🌡️ Capteur OK : " + str(data["temperature"]) + "°C")
Récapitulatif
| Élément | Détail |
|---|---|
| Bibliothèque | Webhook (à installer depuis l'app) |
| Méthode JS | Webhook.getUrlFor({ command, user_id?, content?, redirect_to? }) |
| Méthode PY | Webhook.get_url_for({ "command", "user_id"?, "content"?, "redirect_to"? }) |
Variable content | Données reçues (body POST ou content défini dans l'URL) |
Variable options | Métadonnées HTTP : url, method, params, headers, ip |
| Sécurité | URLs sécurisées automatiquement, rate limiting intégré |
| Méthodes HTTP | GET (avec redirection optionnelle) et POST |
| Format URL | https://hook.botstrike.net/wh/{token} |