Using Webhooks to Connect External Apps

Webhooks let external apps send events to TipLink. When something happens in another app (Discord, Home Assistant, custom programs), it can notify TipLink and trigger your alerts and actions.

Quick Start Guide

Step 1: Enable the Webhook Server

1. Open Settings (gear icon) from the sidebar.
2. Find "Webhook API Settings".
3. Toggle "Enable Webhook API Server". If the toggle is on the left, it means this feature is disabled.
4. Your changes are saved automatically.

tip

Default port is 3821. Only change this if another program is using it.

[IMAGE PLACEHOLDER: Settings page - Webhook API Settings toggle]

Step 2: Create a Webhook Platform

1. Go to Platforms tab.
2. Click "Webhook" at the top of the page.
3. Set a Platforn Name of your choice (this is a label used to remember what the hook is for).
4. Optional: Set a custom API Token of your choice - you can change this later. Leave the field blank and we'll generate one for you.
5. Click Create Account.

[IMAGE PLACEHOLDER: Platform selection showing Webhook option]

Step 3: Connect It

1. Find your webhook in Platforms
2. Click "Connect"
3. The button will change to "Disconnected" (red) if successful.

[IMAGE PLACEHOLDER: Connect button for webhook platform]

warning

Webhooks only work when the webhook server is enabled, and the webhook you're trying to use is connected.

Step 4: Copy Your Credentials

1. Find your webhook in Platforms
2. Click the configure button on the right (it looks like a person next to a gear).
3. Use the copy buttons:

• Webhook URL - Where to send requests
• API Token
  • View: See the token in the field provided.
  • Copy: Automatically copy the API Token to your clipboard.
  • Regenerate: Change the valid API Token by clicking "Regenerate".
• Test Command - You can copy a ready-to-use cURL command using the button provided to test your webhook in tools like Command Prompt, Powershell, Postman, etc.

[IMAGE PLACEHOLDER: Webhook config modal with copy buttons]

Didn't work?

Jump to the Troubleshooting section below. The most common issue is forgetting to click "Connect" in Step 3!

---

Creating Alerts

1. Go to Alerts → Create New Alert.
2. Give it a Title (e.g., "Discord Command").
3. Under Platforms, select "Webhook".
4. Under "Select Webhook Platform" pick the webhook(s) you'd like to trigger this alert.
5. Pick "POST Request" from "Event Type".
6. Configure the minimum/ maximum boundaries for event values.
7. Finish setting up Actions for your Alert, or it won't be triggered!

How to use "Value"

The minimum/ maximum boundaries refer directly to the value index in your webhook payloads. If you don't plan to use this, just set it to 1.

[IMAGE PLACEHOLDER: Alert creation with webhook selected]

Optional: Value Filters

Want alerts only for amounts over $5? Include value in your webhook data, then:

1. Enter a "Minimum Value" → set to 5
2. Optional: Disable "Only Use Minimum Value" to set a ceiling value.

[IMAGE PLACEHOLDER: Min/max value configuration]

---

Sending Webhook Requests

A webhook request needs three things:

1. URL - Where to send it
2. Token - Your API key
3. Data - The information to send

Request Format

POST http://127.0.0.1:3821/webhook/YOUR_ACCOUNT_ID
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "value": 25.00,
  "username": "CoolUser123",
  "message": "Thanks!",
  "custom_field": "anything"
}

The entire JSON object becomes your event data.

Common fields:

• value (number) - For filtering by amount
• username (text) - Who triggered it
• message (text) - Display text
• Any other fields you want!

Code Examples

Example 1: Discord Bot (JavaScript/Node.js)

// After someone uses a !donate command in Discord
const axios = require('axios');

async function notifyTipLink(amount, username, message) {
  await axios.post('http://127.0.0.1:3821/webhook/YOUR_ACCOUNT_ID', {
    value: amount,
    username: username,
    message: message
  }, {
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN'
    }
  });
}

// Usage
await notifyTipLink(10.00, 'DiscordUser123', 'Thanks for the stream!');

Example 2: Home Assistant (Smart Home)

# This triggers when your doorbell rings
automation:
  - alias: "Doorbell Rang - Show Overlay"
    trigger:
      platform: state
      entity_id: binary_sensor.doorbell
      to: 'on'
    action:
      service: rest_command.tiplink_webhook
      data:
        message: "Someone is at the door!"
        location: "Front Door"

# Configuration
rest_command:
  tiplink_webhook:
    url: "http://127.0.0.1:3821/webhook/YOUR_ACCOUNT_ID"
    method: POST
    headers:
      Authorization: "Bearer YOUR_API_TOKEN"
      Content-Type: "application/json"
    payload: '{"message": "{{ message }}", "location": "{{ location }}"}'

Example 3: Python Script

import requests

def send_to_tiplink(value, username, message):
    requests.post(
        'http://127.0.0.1:3821/webhook/YOUR_ACCOUNT_ID',
        json={
            'value': value,
            'username': username,
            'message': message
        },
        headers={
            'Authorization': 'Bearer YOUR_API_TOKEN'
        }
    )

# Usage
send_to_tiplink(5.00, 'PythonUser', 'Hello from Python!')

Example 4: Simple Command Line Test (Windows PowerShell)

curl -X POST http://127.0.0.1:3821/webhook/YOUR_ACCOUNT_ID `
  -H "Authorization: Bearer YOUR_API_TOKEN" `
  -H "Content-Type: application/json" `
  -d '{\"value\": 10.00, \"username\": \"TestUser\", \"message\": \"Test!\"}'

---

Troubleshooting

403 Forbidden

Click "Connect" on your webhook platform

401 Unauthorized

Copy correct API token from webhook settings (click 👁️ eye icon)

404 Not Found

Use "Copy Webhook URL" to get correct account ID

Nothing Happens

Check:

• Webhook server enabled in Settings?
• Webhook connected?
• Alert created and enabled (including at least one action)?
• Value matches min/max filters?

Server Won't Start

Change webhook server port number in Settings, then restart TipLink (another app might be using 3821)

---

Advanced Tips

Using Webhook Data in Overlays

Reference webhook fields in your overlays:

• {{username}} - The username field
• {{message}} - The message field
• {{value}} - The value/amount
• {{any_field}} - Any custom field you send

[IMAGE PLACEHOLDER: Overlay editor with webhook placeholders]

String to Number Conversion

TipLink auto-converts string numbers: "10.50" → 10.50
Non-numeric strings like "ten dollars" will be rejected.

---

Technical Reference

Endpoint

POST http://127.0.0.1:<port>/webhook/<account-id>

• Default port: 3821
• Get account ID from platform config

Headers

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Request Body

Any valid JSON object becomes event data.

Response Codes

Code	Meaning	Action
200	Success	Event created
400	Bad request	Check JSON format
401	Unauthorized	Verify API token
403	Webhook disabled	Click "Connect"
404	Not found	Check account ID
500	Server error	Contact support

Success Response

{
  "success": true,
  "message": "Event created successfully",
  "data": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "platform": "webhook",
    "accountId": "your-account-id",
    "type": "post_request",
    "createdAt": "2025-12-31T12:00:00.000Z"
  }
}