🌙
Introduction
Installation
Générer URL
Recevoir
Variables
Options
Sécurité
Exemples
Récapitulatif

🔗 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 ?

🔗 URL webhook
→
🌐 Serveur BotStrike
→
⚡ Commande exécutée
💡 Bon à savoir — Les URLs webhook sont sécurisées automatiquement par BotStrike. Personne ne peut forger ou modifier une URL.

Installation

Avant d'utiliser Webhook dans votre code, installez la bibliothèque depuis l'application :

  1. Ouvrez votre bot dans BotStrike
  2. Allez dans l'onglet Bibliothèques (📚)
  3. Trouvez Webhook dans la liste
  4. Appuyez sur Installer
⚠️ Important — Si vous essayez d'utiliser 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ètreTypeRequisDescription
commandstring✅ OuiNom de la commande à déclencher (ex: "confirm", "/validate")
user_idstring/number❌ NonID Telegram de l'utilisateur cible. Par défaut : utilisateur courant
contentstring❌ NonDonnées à transmettre à la commande (récupérables via la variable content)
redirect_tostring❌ NonURL vers laquelle rediriger l'utilisateur après le déclenchement

Exemple minimal

JavaScript
Python

// 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

JavaScript
Python

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...
💡 À noter — Le / 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éthodeComportement
GETDéclenche la commande. Si redirect_to est défini, redirige le navigateur après exécution.
POSTDéclenche la commande. Le corps de la requête (body) est accessible via la variable content.

Exemple : commande de confirmation

JavaScript
Python

// 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é !")
💡 Pas de différence de code — La commande ne sait pas si elle a été déclenchée par Telegram ou par un webhook. Utilisez la variable 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 content défini — la valeur passée à getUrlFor({ content: "..." })
  • Sinon — null

options

Dictionnaire contenant les métadonnées de la requête HTTP :

CléTypeDescription
urlstringURL complète qui a été visitée
methodstring"GET" ou "POST"
paramsdictParamètres de l'URL (query string)
headersdictEn-têtes de la requête HTTP
ipstringAdresse IP du visiteur

Détecter un appel webhook

JavaScript
Python

// 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.

JavaScript
Python

// 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.

JavaScript
Python

// 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)
⚠️ Rate limit — Les URLs webhook sont limitées à 60 requêtes par minute par adresse IP pour prévenir les abus.

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
🚫 Ne jamais faire — N'essayez pas de construire manuellement des URLs webhook. Utilisez toujours 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.

JavaScript
Python

// _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.

JavaScript
Python

// _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.

JavaScript
Python

// _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émentDétail
BibliothèqueWebhook (à installer depuis l'app)
Méthode JSWebhook.getUrlFor({ command, user_id?, content?, redirect_to? })
Méthode PYWebhook.get_url_for({ "command", "user_id"?, "content"?, "redirect_to"? })
Variable contentDonnées reçues (body POST ou content défini dans l'URL)
Variable optionsMétadonnées HTTP : url, method, params, headers, ip
SécuritéURLs sécurisées automatiquement, rate limiting intégré
Méthodes HTTPGET (avec redirection optionnelle) et POST
Format URLhttps://hook.botstrike.net/wh/{token}
✅ Prêt ! — Vous pouvez maintenant connecter votre bot Telegram au reste du monde. Créez des liens d'action, recevez des callbacks de paiement, intégrez votre bot à votre site web — tout est possible avec Webhook.