Telegram PR Webhook Hook

Sends Telegram notifications with PR URLs and Vercel preview links when new pull requests are created via the gh CLI.

When to Use This Hook

Attach this hook when you need to:

• Receive instant Telegram alerts when Claude Code creates a pull request, including the PR URL for immediate review access
• Automatically include Vercel preview deployment URLs alongside PR notifications for visual review of frontend changes
• Maintain a Telegram-based PR activity feed for team members who prefer mobile notifications over email or web-based PR alerts

Consider alternatives when:

• Your team uses GitHub's built-in notification system or a dedicated PR review tool like Reviewable that already handles notifications
• You need advanced PR notification features like diff previews, approval tracking, or comment threading that require richer formatting

Quick Start

Configuration

Copy
name: telegram-pr-webhook-hook
type: hook
trigger: PostToolUse
category: automation

Example Trigger

Copy
gh pr create --title "feat: add dark mode" --body "Implements dark mode toggle"
# Hook detects PR creation and sends Telegram notification

Example Output

Telegram PR Notification Sent:
PR Created: feat: add dark mode
PR URL: https://github.com/org/repo/pull/42
Vercel Preview: https://my-app-pr-42.vercel.app
Chat: -1001234567
Delivery: Success

Core Concepts

PR Webhook Overview

Aspect	Details
Trigger Point	PostToolUse on Bash commands containing gh pr create
Detection Method	Python script parses tool input and output for PR creation
PR URL Extraction	Parsed from gh pr create command output
Preview URL	Constructed from VERCEL_PROJECT_NAME and VERCEL_TEAM_SLUG
Required Variables	TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID
Optional Variables	VERCEL_PROJECT_NAME, VERCEL_TEAM_SLUG for preview URLs

PR Notification Workflow

PostToolUse (Bash matcher)
    |
    v
[Python script: telegram-pr-webhook.py]
    |
    v
[Parse tool input for "gh pr create" command]
    |          |
   No         Yes
    |          |
 [Skip]       v
         [Extract PR URL from command output]
              |
              v
         [VERCEL_PROJECT_NAME set?]
              |          |
             No         Yes
              |          |
              |          v
              |     [Construct Vercel preview URL]
              |          |
              +----------+
              |
              v
         [Build Telegram message with PR + preview URLs]
              |
              v
         [POST to Telegram sendMessage API]

Configuration

Parameter	Type	Default	Description
TELEGRAM_BOT_TOKEN	string	(required)	Bot authentication token from @BotFather
TELEGRAM_CHAT_ID	string	(required)	Target chat ID for PR notification delivery
VERCEL_PROJECT_NAME	string	(optional)	Vercel project name used to construct preview deployment URLs
VERCEL_TEAM_SLUG	string	(optional)	Vercel team slug for constructing the correct preview URL domain
timeout	integer	30	Maximum seconds for the Python script to complete execution

Best Practices

1. Configure Vercel variables for full preview URLs - Set VERCEL_PROJECT_NAME and VERCEL_TEAM_SLUG to enable automatic preview URL construction. This turns the notification from a simple PR link into a one-click review experience with both code and visual preview access.

2. Deploy the Python script to the hooks directory - The hook expects the script at $CLAUDE_PROJECT_DIR/.claude/hooks/telegram-pr-webhook.py. Commit this script to version control so all team members get PR notifications without manual setup.

3. Use a dedicated review group chat - Create a Telegram group specifically for PR notifications. This separates PR activity from session notifications and allows team members to discuss PRs directly in the context of the notification message thread.

4. Customize the message format for your workflow - Modify the Python script to include additional PR metadata such as the branch name, number of changed files, or assigned reviewers. This context helps reviewers prioritize which PRs to look at first.

5. Handle the 30-second timeout for slow networks - The default timeout gives the Python script 30 seconds to parse the PR data and deliver the Telegram message. If you experience timeouts on slow networks, increase this value or add retry logic to the Python script.

Common Issues

1. Hook does not detect PR creation - The Python script matches gh pr create in the Bash command. If you use alternative PR creation methods like hub pull-request or the GitHub web interface, the hook will not fire. Standardize on gh pr create for consistent notification delivery.

2. Vercel preview URL is incorrect or broken - The preview URL is constructed from environment variables, not fetched from the Vercel API. If your Vercel project name or team slug contains special characters or differs from the expected format, the URL will be invalid. Verify by manually checking a known preview URL.

3. Python script fails with import errors - The script requires Python 3 with standard library modules. If your system's python3 command points to a different version or a virtual environment without required modules, the script will fail silently. Verify Python 3 availability with python3 --version.