webhooks-trigger/README.md

Webhooks Trigger - Stream Deck Plugin

A professional Stream Deck plugin for sending HTTP webhook requests with the press of a button. Built with TypeScript and the official Elgato Stream Deck SDK.

🚀 Features

• Complete HTTP Support: GET, POST, PUT, PATCH, DELETE methods
• Flexible Configuration: Customizable URL, headers, body, and HTTP method
• JSON Validation: Real-time validation of headers and body JSON
• JSON Beautification: Automatic JSON formatting with proper indentation
• Configuration Verification: Complete validation with error detection
• Visual Feedback: Success/failure indication directly on Stream Deck
• Comprehensive Logging: Detailed logs for debugging and monitoring
• Modern UI: Clean interface with SDPI components

📦 Installation

Prerequisites

• Official Stream Deck software installed
• Node.js 20+ and npm
• Stream Deck CLI (npm install -g @elgato/cli)

Developer Installation

1. Clone the repository

   git clone <repository-url>
   cd webhooks-trigger
   

2. Install dependencies

   npm install
   

3. Build the plugin

   npm run build
   

4. Install in development mode

   streamdeck dev
   cd com.mr-kayjaydee.webhooks-trigger.sdPlugin
   streamdeck link
   

5. Restart the plugin (after modifications)

   npm run restart
   

⚙️ Configuration

Configuration Fields

Field	Description	Required	Example
URL	Webhook destination URL	✅	https://webhook.site/abc123
HTTP Method	HTTP method to use	✅	POST
Headers	HTTP headers in JSON format	❌	{"Content-Type": "application/json"}
Body	Request body content	❌	{"message": "Hello!"}

Note

: Button title is managed natively by Stream Deck through the standard interface.

Configuration Examples

Simple GET Webhook

URL: https://api.example.com/webhook
Method: GET
Headers: {"Authorization": "Bearer token123"}
Body: (empty)

POST Webhook with JSON

URL: https://webhook.site/abc123
Method: POST
Headers: {"Content-Type": "application/json"}
Body: {"event": "button_pressed", "timestamp": "now"}

Discord Notification

URL: https://discord.com/api/webhooks/your-webhook-url
Method: POST
Headers: {"Content-Type": "application/json"}
Body: {"content": "Message from Stream Deck!"}

🛠️ User Interface

Validation Buttons

• Beautify JSON: Automatically formats JSON with proper indentation
• Validate JSON: Checks JSON syntax and displays errors
• Verify Configuration: Complete validation of all configuration settings

Validation Messages

• Errors: Displayed in red below fields for 5 seconds
• Success: Displayed in green for 5 seconds
• Real-time Validation: Automatic verification during input
• Timeout Management: Previous timeouts are automatically cleared

Stream Deck Visual Feedback

• ✅ Green Checkmark: Request sent successfully (status 200-299)
• ❌ Red X: Error occurred (invalid URL, malformed JSON, network error)

📋 Validation Rules

URL Validation

• ✅ Supported protocols: http:// and https://
• ✅ Valid URL format required
• ❌ Relative URLs not supported

Headers Validation

• ✅ Valid JSON object: {"key": "value"}
• ❌ Arrays not supported: ["value1", "value2"]
• ❌ Primitives not supported: "string" or 123

Body Validation

• ✅ Valid JSON or plain text
• ✅ Empty allowed (optional)
• ⚠️ Warning if body is empty for POST/PUT/PATCH
• ⚠️ Warning if body is present for GET

Best Practices

• Content-Type Recommended: Add {"Content-Type": "application/json"} for JSON body requests
• Authentication Headers: Use {"Authorization": "Bearer token"} for authentication
• Pre-validation: Use "Verify Configuration" button before first use

🔧 Development

Project Structure

webhooks-trigger/
├── src/                                 # TypeScript source code
│   ├── actions/
│   │   └── send-webhook.ts             # Main plugin action
│   ├── services/                       # Service modules
│   │   ├── validation-service.ts       # Validation logic
│   │   ├── webhook-request-builder.ts  # HTTP request construction
│   │   ├── webhook-executor.ts         # Request execution
│   │   └── settings-manager.ts         # Settings management
│   ├── types/
│   │   └── webhook-settings.ts         # TypeScript types and constants
│   └── plugin.ts                       # Plugin entry point
├── com.mr-kayjaydee.webhooks-trigger.sdPlugin/  # Stream Deck plugin
│   ├── manifest.json                   # Plugin metadata
│   ├── ui/
│   │   ├── send-webhook.html           # User interface
│   │   └── send-webhook.js             # Frontend JavaScript
│   ├── bin/
│   │   ├── plugin.js                   # Compiled code (generated)
│   │   └── package.json                # ES module config (generated)
│   └── imgs/                           # Icons and assets
├── package.json                        # Dependencies and scripts
├── tsconfig.json                       # TypeScript configuration
└── rollup.config.mjs                  # Build configuration

Available Scripts

npm run build          # Compile TypeScript to JavaScript
npm run watch          # Development mode with watch and auto-restart
npm run restart        # Build + restart plugin

HTTP Methods

• GET: Retrieve data from the server
• POST: Send data to create new resources
• PUT: Update or create resources
• PATCH: Partially update resources
• DELETE: Remove resources

Error Handling

The plugin handles various error scenarios:

• Network Errors: Connection timeouts, DNS resolution failures
• HTTP Errors: 4xx and 5xx status codes
• Validation Errors: Invalid JSON, malformed URLs
• Configuration Errors: Missing required fields

🚨 Troubleshooting

Common Issues

1. Plugin Not Appearing

   • Ensure Stream Deck software is running
   • Check if plugin is properly linked with streamdeck link
   • Restart Stream Deck software

2. Webhook Not Sending

   • Verify URL is accessible
   • Check network connectivity
   • Validate JSON syntax in headers/body
   • Review Stream Deck logs

3. JSON Validation Errors

   • Use the "Beautify JSON" button to format
   • Check for missing quotes, commas, or brackets
   • Ensure headers are objects, not arrays

Debug Logging

The plugin includes comprehensive logging. To view logs:

1. Open Stream Deck software
2. Go to preferences → Advanced → Enable debug logging
3. Check the plugin logs directory

📄 License

This project is licensed under the MIT License.

👤 Author

Mr-KayJayDee

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📊 System Requirements

• Stream Deck Software: 6.5 or higher
• Operating System:
  • Windows 10 or higher
  • macOS 12 or higher
• Node.js: Version 20 or higher