HTTP Request Action

Send custom HTTP requests to any API or webhook endpoint. Make GET, POST, PUT, PATCH, or DELETE requests with custom headers, body content, and configuration options.

What You Need

• The API endpoint URL you want to call
• Knowledge of the HTTP method required (GET, POST, etc.)
• Any authentication credentials (API keys, tokens)
• Understanding of request body format if sending data

Quick Start

1. Create or edit an alert
2. Add the HTTP Request action
3. Select HTTP method (GET, POST, etc.)
4. Enter the URL
5. Add headers if needed (JSON format)
6. Add request body if needed
7. Configure timeout and options
8. Save and test

Screenshot Coming Soon

Configuration interface screenshot will be added here.

Configuration Options

Request Method

HTTP Method

• The type of HTTP request to send
• Options:
  • GET: Retrieve data (most common for reading)
  • POST: Send data to create resources
  • PUT: Update existing resources (full replacement)
  • PATCH: Partially update resources
  • DELETE: Remove resources
• Required field

Method Selection

• Use GET for triggering endpoints that don't need data
• Use POST for sending alert data to webhooks
• Use PUT/PATCH for updating external systems
• Use DELETE for cleanup or removal operations

URL Configuration

URL

• The complete endpoint URL
• Must start with http:// or https://
• Can include query parameters: ?param1=value1&param2=value2
• Supports placeholders: {username}, {amount}
• Required field

Example URLs:

https://api.example.com/webhook
https://hooks.slack.com/services/YOUR/WEBHOOK/URL
http://localhost:3000/alert?user={username}&amount={amount}

Headers

Headers (JSON)

• Custom HTTP headers as JSON object
• Format: {"Header-Name": "value", "Another-Header": "value"}
• Common headers:
  • Content-Type: Specify body format
  • Authorization: API authentication
  • User-Agent: Identify your application
• Optional (default headers sent automatically)

Example Headers:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN",
  "X-Custom-Header": "value"
}

JSON Format

Headers must be valid JSON. Use double quotes around both keys and values. Invalid JSON will cause the request to fail.

Request Body

Request Body

• Data to send with POST/PUT/PATCH requests
• Can be JSON, form data, or plain text
• Supports dynamic placeholders
• Optional (not used for GET/DELETE typically)

Example Bodies:

JSON:

{
  "username": "{username}",
  "amount": "{amount}",
  "message": "{message}",
  "timestamp": "{timestamp}"
}

Form Data:

username={username}&amount={amount}&message={message}

Plain Text:

User {username} triggered alert with amount {amount}

Body Content Type

• Determines how body is formatted and sent
• Options:
  • Auto-detect: Attempts to determine from body content
  • JSON (application/json): For JSON APIs
  • Form URL Encoded (application/x-www-form-urlencoded): For form submissions
  • Plain Text (text/plain): For simple text data
  • XML (application/xml): For XML APIs
• Optional (auto-detect if not specified)

Auto-Detect

Auto-detect examines your body content:

• Starts with { or [ → JSON
• Contains key=value& → Form
• Starts with < → XML
• Otherwise → Plain Text

Advanced Options

Timeout (seconds)

• Maximum time to wait for response
• In seconds
• Default: 30 seconds
• Prevents hanging on slow/unresponsive endpoints
• Optional

Follow Redirects

• Automatically follow HTTP redirects (301, 302, etc.)
• Checkbox (on/off)
• Enabled by default
• Disable if you need to handle redirects manually

Validate SSL Certificate

• Verify SSL/TLS certificates are valid
• Checkbox (on/off)
• Enabled by default
• Disable for self-signed certificates or development

SSL Validation

Only disable SSL validation if you trust the endpoint and understand the security implications. This makes you vulnerable to man-in-the-middle attacks.

Setup Guide

Basic GET Request

1. Configure Request

   • Method: GET
   • URL: https://api.example.com/trigger
   • Leave headers/body empty

2. Add Authentication (if needed)

   • Headers: {"Authorization": "Bearer YOUR_TOKEN"}

3. Test

   • Save and trigger alert
   • Check API receives request

POST JSON Data

1. Set Method

   • Method: POST
   • URL: Your webhook URL

2. Configure Headers

   {
     "Content-Type": "application/json"
   }

3. Add Body

   {
     "event_type": "tip",
     "user": "{username}",
     "amount": {amount},
     "message": "{message}"
   }

4. Set Body Type

   • Body Content Type: JSON

5. Test

   • Trigger alert
   • Verify endpoint receives JSON

Home Assistant Webhook

To trigger Home Assistant automation:

1. Create Webhook in Home Assistant

   • Configuration → Automations → Create
   • Trigger type: Webhook
   • Note the webhook ID

2. Configure TipLink

   • Method: POST
   • URL: http://homeassistant.local:8123/api/webhook/YOUR_WEBHOOK_ID
   • Body Type: JSON
   • Body:

   {
     "username": "{username}",
     "amount": "{amount}"
   }

Slack Webhook

To post messages to Slack:

1. Create Slack Webhook

   • Slack → Apps → Incoming Webhooks
   • Copy webhook URL

2. Configure TipLink

   • Method: POST
   • URL: Your Slack webhook URL
   • Headers:

   {
     "Content-Type": "application/json"
   }

   • Body:

   {
     "text": "{username} tipped ${amount}!"
   }

Discord Webhook (Alternative)

Alternative to built-in Discord action:

1. Get Discord Webhook URL

   • Discord → Channel Settings → Integrations → Webhooks

2. Configure TipLink

   • Method: POST
   • URL: Your Discord webhook URL
   • Body:

   {
     "content": "**{username}** just tipped **${amount}**!"
   }

API with Authentication

For APIs requiring authentication:

1. Bearer Token Auth

   • Headers:

   {
     "Authorization": "Bearer YOUR_API_TOKEN",
     "Content-Type": "application/json"
   }

2. API Key Auth

   • Headers:

   {
     "X-API-Key": "YOUR_API_KEY"
   }

3. Basic Auth

   • Headers:

   {
     "Authorization": "Basic BASE64_ENCODED_CREDENTIALS"
   }

Self-Signed Certificate

For local HTTPS endpoints with self-signed certs:

1. Disable SSL Validation

   • Uncheck "Validate SSL Certificate"

2. Use HTTPS URL

   • URL: https://localhost:8443/webhook

3. Test

   • Verify connection works
   • Re-enable SSL validation when not needed

Common Use Cases

Webhook Notification

• Method: POST
• URL: Your webhook service
• Body: JSON with alert data
• Notify external systems

Update Dashboard

• Method: PUT
• URL: Dashboard API endpoint
• Body: Stats/metrics to update
• Real-time dashboard updates

Log to Database

• Method: POST
• URL: Logging service endpoint
• Body: Event data
• Persistent event storage

Trigger IFTTT

• Method: POST
• URL: https://maker.ifttt.com/trigger/{event}/with/key/{key}
• Body: IFTTT value1/value2/value3 JSON
• Connect to hundreds of services

Control Smart Home

• Method: POST
• URL: Smart home hub endpoint
• Body: Device commands
• Turn on lights, change colors, etc.

Send to Analytics

• Method: POST
• URL: Analytics API
• Body: Event tracking data
• Track viewer engagement

Custom Bot Integration

• Method: POST
• URL: Bot webhook endpoint
• Body: Command/action data
• Trigger custom bot actions

Troubleshooting

Request fails / no response

• Verify URL is correct and reachable
• Check firewall isn't blocking outbound requests
• Test URL in browser or Postman first
• Check TipLink logs for error details

401 Unauthorized / 403 Forbidden

• Verify authentication headers
• Check API key/token is valid
• Ensure proper header format
• Check API permissions

400 Bad Request

• Verify body format matches API expectation
• Check Content-Type header
• Validate JSON syntax
• Ensure required fields present

Timeout errors

• Increase timeout value
• Check endpoint responsiveness
• Verify network connectivity
• Endpoint may be overloaded

SSL certificate errors

• Verify endpoint has valid SSL cert
• Use http:// for local/dev endpoints
• Or disable SSL validation (not recommended for production)

Placeholders not replaced

• Check placeholder syntax: {username} not username
• Verify placeholder is valid for trigger type
• Placeholders work in URL, headers, and body

JSON parsing errors

• Validate JSON syntax (use JSON validator)
• Ensure double quotes (not single)
• Check for trailing commas (not allowed in JSON)
• Use JSON linter before saving

Body not sent

• Body only sent with POST/PUT/PATCH
• GET and DELETE typically don't use body
• Check method is correct

Best Practices

URL Construction:

• Always include protocol (http:// or https://)
• Use HTTPS when possible for security
• Encode special characters in URLs
• Test URLs before using in production

Headers:

• Include Content-Type when sending body
• Use proper authentication headers
• Keep headers in valid JSON format
• Don't include sensitive data in custom headers if logging enabled

Request Body:

• Match format to API requirements
• Validate JSON before saving
• Use appropriate Content-Type
• Keep body size reasonable (< 1MB)

Authentication:

• Use environment variables for sensitive tokens (if possible)
• Rotate API keys regularly
• Use token-based auth over basic auth
• Check API rate limits

Error Handling:

• Set reasonable timeouts (10-30 seconds)
• Check API documentation for error responses
• Log errors for debugging
• Have fallback behavior if request fails

Testing:

• Test with tools like Postman first
• Start with simple GET requests
• Add complexity gradually
• Test error scenarios (invalid URL, timeout, etc.)

Security:

• Use HTTPS for production
• Keep SSL validation enabled
• Don't log sensitive data
• Secure API keys/tokens
• Check endpoint's CORS policy if relevant

Performance:

• Keep request body small
• Use appropriate timeouts
• Consider rate limiting for high-frequency alerts
• Cache responses if applicable (external to TipLink)

Technical Reference

HTTP Methods:

• GET: Safe, idempotent, cacheable
• POST: Not idempotent, creates resources
• PUT: Idempotent, replaces resources
• PATCH: Not idempotent, updates resources
• DELETE: Idempotent, removes resources

Common Status Codes:

• 200 OK: Success
• 201 Created: Resource created (POST)
• 204 No Content: Success, no response body
• 400 Bad Request: Invalid request
• 401 Unauthorized: Authentication failed
• 403 Forbidden: No permission
• 404 Not Found: Endpoint doesn't exist
• 429 Too Many Requests: Rate limited
• 500 Internal Server Error: Server error
• 503 Service Unavailable: Server overloaded

Headers:

• Content-Type: Format of request body
• Accept: Expected response format
• Authorization: Authentication credentials
• User-Agent: Client identification
• Custom Headers: Application-specific (X-*)

Content Types:

• application/json: JSON data
• application/x-www-form-urlencoded: Form data
• text/plain: Plain text
• application/xml: XML data
• multipart/form-data: File uploads (not supported)

Placeholders: Available placeholders depend on trigger type:

• {username} - Viewer username
• {amount} - Tip/sub amount
• {message} - Viewer message
• {timestamp} - Event timestamp
• {event_type} - Type of event
• More may be available per platform

Timeout Behavior:

• Default: 30 seconds
• Minimum: 1 second
• Maximum: 300 seconds (5 minutes)
• Timeout triggers error, doesn't retry

Redirect Handling:

• Follows 301, 302, 303, 307, 308 by default
• Max 10 redirects
• Disable to handle manually
• Useful for tracking redirect chains

SSL/TLS:

• Validates certificates by default
• Uses system certificate store
• Supports TLS 1.2 and 1.3
• Disable only for dev/testing

Request Limits:

• Max URL length: ~2000 characters
• Max header size: 8KB total
• Max body size: 10MB
• No rate limiting on send (check API limits)

Error Handling:

• Logs errors to console
• No automatic retry
• No response validation (any status code accepted)
• Network errors fail silently (logged)

Performance:

• Asynchronous (non-blocking)
• Multiple simultaneous requests supported
• DNS caching enabled
• Keep-alive connections not maintained

Response Handling:

• Response status logged
• Response body not stored/displayed
• Use webhook logs on receiving end
• No response processing in TipLink