Merge pull request #11 from devrabie/feature-webhook-secret-token-validation

Feature webhook secret token validation

Author: devrabie

README.md

@@ -116,5 +116,51 @@ $redis = \Longman\TelegramBot\Telegram::getRedis();
 
 ---
 
+## 🔐 Webhook Secret Token
+
+For enhanced security, you can set a secret token when you [set your webhook](https://core.telegram.org/bots/api#setwebhook). Telegram will then send this token in the `X-Telegram-Bot-Api-Secret-Token` header with every update. This library can automatically validate this token for you.
+
+### 1. Set the Webhook with a Secret Token
+
+When setting your webhook, provide a `secret_token`:
+
+```php
+$telegram->setWebhook('https://your-domain.com/hook.php', [
+    'secret_token' => 'YOUR_SECRET_TOKEN',
+]);
+```
+
+### 2. Configure Your Bot to Verify the Token
+
+In your webhook handler (e.g., `hook.php`), set the same secret token on your `Telegram` object. The library will then automatically check the header on incoming requests and throw an exception if the token is missing or invalid.
+
+```php
+<?php
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+$bot_api_key  = 'YOUR_BOT_API_KEY';
+$bot_username = 'YOUR_BOT_USERNAME';
+$bot_secret   = 'YOUR_SECRET_TOKEN';
+
+try {
+    $telegram = new Longman\TelegramBot\Telegram($bot_api_key, $bot_username);
+
+    // Set the secret token for incoming webhook requests
+    $telegram->setSecretToken($bot_secret);
+
+    // Handle the update
+    $telegram->handle();
+
+} catch (Longman\TelegramBot\Exception\TelegramException $e) {
+    // Log the error
+    error_log($e->getMessage());
+}
+```
+
+This ensures that only requests from Telegram with the correct secret token are processed by your bot.
+
+---
+
 🙏 Acknowledgments
 A huge thanks to the original developers of longman/php-telegram-bot for their incredible work that formed the foundation of this project.

src/Request.php

@@ -1065,4 +1065,14 @@ public static function setChatMenuButton(array $data): ServerResponse
     {
         return static::send('setChatMenuButton', $data);
     }
+
+    /**
+     * Get the secret token header from the request
+     *
+     * @return string|null
+     */
+    public static function getSecretTokenHeader(): ?string
+    {
+        return $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? null;
+    }
 }

src/Telegram.php

@@ -36,7 +36,7 @@ class Telegram
      *
      * @var string
      */
-    protected $version = '1.0.7';
+    protected $version = '1.0.9';
 
     /** @var \Redis|null */
     private static $redis_connection;
@@ -69,6 +69,13 @@ class Telegram
      */
     protected $input = '';
 
+    /**
+     * Secret token to authorise webhook requests
+     *
+     * @var string
+     */
+    protected $secret_token = '';
+
     /**
      * Custom commands paths
      *
@@ -502,6 +509,10 @@ public function handle(): bool
             throw new TelegramException('Bot Username is not defined!');
         }
 
+        if ($this->secret_token !== '' && $this->secret_token !== Request::getSecretTokenHeader()) {
+            throw new TelegramException('Secret token is invalid!');
+        }
+
         $input = Request::getInput();
         if (empty($input)) {
             throw new TelegramException('Input is empty! The webhook must not be called manually, only by Telegram.');
@@ -1281,6 +1292,20 @@ public function getUpdateFilter(): ?callable
         return $this->update_filter;
     }
 
+    /**
+     * Set the secret token to be used for webhook verification
+     *
+     * @param string $secret_token
+     *
+     * @return Telegram
+     */
+    public function setSecretToken(string $secret_token): Telegram
+    {
+        $this->secret_token = $secret_token;
+
+        return $this;
+    }
+
     /**
      * Converts the name of a class into the name of a command.
      *