Webhook Integration - Complete Guide to HTTP Triggers

Webhooks are the most versatile way to trigger Echobell notifications. This comprehensive guide covers everything you need to know about integrating webhook-based alerts into your systems, from basic concepts to advanced usage patterns.

What's webhook

A webhook is a way for one application to provide real-time information to other applications through HTTP callbacks. Think of it as a phone number that you give to someone - when they call that number, your phone rings. In the digital world, when something happens in one system (like high CPU usage, a failed build, or a new order), it sends an HTTP request to a URL (the webhook) that you provided, triggering an action in your system.

For example, when your server's CPU usage goes too high, your monitoring system can call Echobell's webhook URL, which then triggers a notification to alert you. This happens automatically and in real-time, without you having to constantly check the CPU usage yourself.

Webhooks are the foundation of event-driven architectures and are supported by virtually all modern cloud services, monitoring tools, and SaaS platforms. They're lightweight, fast, and don't require any special infrastructure on your side - just an HTTP client.

Benefits of Webhooks

• Real-time: Events trigger notifications instantly, typically within 1-2 seconds
• Universal: Supported by almost every modern service and programming language
• Flexible: Pass custom data to create rich, contextual notifications
• Reliable: HTTP-based, with standard status codes and error handling
• Scalable: No polling required - notifications sent only when events occur

Overview

Channels are how Echobell receives webhooks. Every channel has its own webhook URL, and when that URL is called, the channel sends a notification to all its subscribers.

Creating a channel only takes a name. By default, the channel shows the title, body and externalLink each request sends, exactly as sent — handy for your own scripts, cron jobs and CI steps. When the request comes from another service, you can turn on a custom template and build the notification from the request's data instead.

Webhook URL Format

https://hook.echobell.one/t/{channel-token}

You can find your channel's webhook URL in the channel details view of the Echobell app.

Making Webhook Requests

By default, a channel reads four fields from each request. Field names are case-insensitive (title, Title and TITLE are the same field), and they can go in the query string of a GET, or in a JSON or form-encoded POST body.

GET Request

GET https://hook.echobell.one/t/<channel-token>?title=Backup%20finished&body=Nightly%20backup%20completed

POST Request

Send a JSON body:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "title": "CPU alert",
  "body": "Production CPU usage reached 95%",
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Or a form-encoded body, which is what curl -d sends:

curl -d "title=Hello&body=World" https://hook.echobell.one/t/<channel-token>

Opening the URL in a Browser

A GET with no query string and no body — what a browser or a chat app's link preview sends — does not notify anyone. The channel answers with a short description of the fields it accepts instead:

{
  "success": true,
  "notificationTriggered": false,
  "message": "This is an Echobell channel webhook. It pushes a notification to the channel's subscribers. Send a title or a body to trigger one.",
  "usage": { "...": "..." }
}

Add a title or a body to send a notification. A POST always notifies, even with an empty body (the title is then the channel name).

POST Only

Each channel has a POST Only switch under Advanced Settings in the Echobell app. It is off by default.

When it is on, only POST can trigger the channel. A GET to the webhook URL is rejected with 405 Method Not Allowed, and no notification is sent:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

HEAD requests are unaffected — they answer 200 and never trigger a notification, whether POST Only is on or off.

Turn it on when the webhook URL ends up somewhere that fetches links automatically — a chat message, a wiki page, a browser address bar — so that previewing or opening the URL cannot fire an alert. Leave it off if any of your callers trigger the channel with GET.

Notification Level

Everyone who subscribes to a channel picks a notification type for it in the app: Normal (active), Time Sensitive or Calling. That choice is the highest level the channel can reach them at. A request can send notificationType to ask for a lower level, never a higher one.

For example, subscribe to your "Production" channel at Calling. Requests for outages leave notificationType out, so they ring like a phone call. Routine events, such as a finished deploy, send notificationType=active and arrive as a normal notification:

curl -d "title=Deploy finished&body=v2.1.0 is live&notificationType=active" \
  https://hook.echobell.one/t/<channel-token>

A teammate who subscribed to the same channel at Time Sensitive gets the outage as a time-sensitive notification, never as a call.

Channels with Custom Template turned on ignore notificationType in the request: every subscriber always gets the level they chose.

Custom Templates

By default a channel shows the title, body and externalLink each request sends. When the request comes from a service whose payload you can't change — a monitoring tool, a CI system, a store — turn on Custom Template under Advanced Settings in the channel's settings and write a title template and a body template. The channel then builds every notification from those templates, and every query parameter and JSON field of the request becomes a variable.

Pass variables through query parameters:

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

Or in a JSON body:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

Template Variables

Use the variables in your notification templates with the {{variableName}} syntax:

Title: Server {{server_name}} Alert
Body: CPU usage has reached {{cpu_usage}}%

When triggered, these templates will be populated with the values provided in your webhook request. See Templates for the full syntax and Conditions to filter which requests notify.

Special Variables

• externalLink: When included in the request, this creates a clickable link in the notification records view, unless the channel has its own external link template.

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

System Time Variables (UTC)

In addition to data you send, Echobell provides read‑only system time variables that are always available in templates and conditions. All values are computed in UTC. Flat fields include date, time, year, month, dayOfWeek, hour, minute, and second. Others — such as sys.dayOfWeekName, sys.epochMs, and sys.epochSeconds — are available only under the sys. namespace. See Conditions for the full list and examples.

Common Use Cases

Webhooks are the most popular trigger method in Echobell and are particularly useful for:

DevOps and Monitoring

• Server Monitoring: CPU, memory, disk usage alerts from monitoring systems like Prometheus or Grafana
• Uptime Monitoring: Website and service availability alerts from Uptime Kuma or UptimeRobot
• Container Monitoring: Docker, Kubernetes pod failures, and resource constraints
• Log Aggregation: Critical errors and exceptions from log management systems

Development and CI/CD

• Build Notifications: Failed builds, test results, deployment status from GitHub Actions or GitLab CI
• Code Quality: Lint errors, security vulnerabilities, code coverage changes
• Repository Events: Pull requests, commits, releases, and collaborator activity
• Deployment Tracking: Successful deployments, rollbacks, and environment changes

Business Applications

• E-commerce: New orders, payment confirmations, inventory warnings, shipping updates
• CRM: New leads, deal closures, support tickets, customer interactions
• Payment Processing: Transaction completions, refund requests, fraud alerts
• Form Submissions: Contact forms, survey responses, registration completions

IoT and Smart Home

• Smart Home Events: Door sensors, motion detection, temperature changes via Home Assistant
• IoT Devices: Sensor readings, device status changes, connectivity issues
• Security Systems: Alarm triggers, camera motion detection, access control events
• Environmental Monitoring: Temperature, humidity, air quality threshold breaches

Trading and Finance

• Market Alerts: Price movements, technical indicators from TradingView
• Portfolio Monitoring: Position changes, margin calls, account balances
• Economic Events: News releases, earning reports, market sentiment changes

See our integration guides for specific setup instructions for popular platforms.

Best Practices

Error Handling

Echobell answers every webhook call with an HTTP status and a JSON body:

• 200 OK: The request was handled. notificationTriggered: true means a notification was sent. notificationTriggered: false means nothing was sent on purpose: the channel's conditions didn't match (conditionsMet: false), or a bare GET got the usage description.
• 400 Bad Request: The channel token is the wrong length. Fix the webhook URL.
• 404 Not Found: No channel has this token (code: "TRIGGER_TOKEN_NOT_FOUND"; on an old /d/ URL, DIRECT_KEY_NOT_FOUND). The channel was deleted or its webhook URL was reset.
• 405 Method Not Allowed: The channel has POST Only turned on and the request wasn't a POST. Switch the caller to POST, or turn the setting off.
• 413 Payload Too Large: The request body is over 1 MiB.
• 429 Too Many Requests: More than 120 requests in a minute for the same webhook URL. The response carries a Retry-After header (in seconds); wait that long before retrying.
• 500 Server Error: Temporary issue, retry with exponential backoff

Check the HTTP status first, then notificationTriggered to know whether a notification went out.

Rate Limiting

Each webhook URL accepts up to 120 requests a minute; requests beyond that get a 429 response.

Implement reasonable delays between webhook calls to avoid overwhelming your notification system:

• For continuous monitoring, batch multiple events into single notifications
• Use conditions to filter out non-critical events
• Consider aggregating rapid-fire events (e.g., multiple errors in short time)
• Avoid sending rapid-fire duplicate triggers to keep critical alerts reliable

Data Security

Only share webhook URLs with trusted systems and services:

• Treat webhook URLs as secrets - they provide direct access to send notifications
• Don't commit webhook URLs to public repositories or share in public documentation
• Rotate webhook URLs periodically or when team members leave
• Use the channel's "Reset Token" feature to invalidate old URLs if compromised
• Consider using environment variables or secret management systems to store URLs

Variable Naming

Use clear, consistent variable names in your webhook calls:

• Use descriptive names: server_name instead of s or srv
• Follow a consistent naming convention across channels
• Document which variables your templates expect
• Validate that all required variables are present before sending

Testing

Test your webhook integration thoroughly before implementing in production:

1. Use tools like curl, Postman, or your language's HTTP client for initial testing
2. Start with simple templates and gradually add complexity
3. Test both GET and POST methods to find what works best
4. Verify that special characters and Unicode are handled correctly
5. Test error scenarios (missing variables, malformed JSON) to understand behavior
6. Use test channels separate from production channels during development

Template Design

Design templates that remain useful even when optional variables are missing:

• Provide default values or fallbacks for optional data
• Structure templates to gracefully handle missing variables
• Test templates with various combinations of present and absent variables
• Use conditional expressions for optional sections

Monitoring

Monitor your webhook integrations to ensure they're working correctly:

• Log successful and failed webhook calls in your application
• Track notification delivery rates and response times
• Set up alerts for webhook errors or unusual patterns
• Periodically review and test critical webhook integrations

Privacy and Security

Understanding how Echobell handles your webhook data:

What Gets Stored

• On Our Servers:

  • Webhook URLs (tokens) - needed to route incoming requests to channels
  • Channel configurations - templates, conditions, settings
  • Subscription relationships - which users subscribe to which channels

• On Your Device:

  • Notification content - the rendered title and body text
  • Trigger history - when notifications were received
  • Variable values - the data passed in webhook calls
  • Links and metadata - externalLink and other associated data

What Doesn't Get Stored

• We don't permanently store the raw webhook payloads
• We don't log or retain sensitive data from your requests
• We don't analyze or process notification content for any purpose
• We don't share your webhook data with third parties

Security Recommendations

• Treat webhook URLs as API keys - they provide authentication-free access to send notifications
• Rotate URLs regularly - use the "Reset Token" feature to generate new URLs
• Use HTTPS clients - while we only accept HTTPS connections, ensure your client validates certificates
• Validate webhook sources - if possible, restrict which IPs or services can call your webhooks
• Monitor for abuse - watch for unusual patterns or unauthorized usage
• Separate environments - use different channels for development, staging, and production

Learn more in our support documentation.

Troubleshooting

If your webhooks aren't working as expected, try these diagnostic steps:

Webhook Not Triggering Notifications

1. Verify the webhook URL is correct

   • Copy the URL directly from the Echobell app
   • Ensure no extra spaces or characters were added
   • Check that you're using https://hook.echobell.one/t/ not any other domain

2. Check if the channel is active

   • Open the channel in the Echobell app
   • Verify it hasn't been deleted or archived
   • Confirm you haven't reset the webhook token (which would invalidate the URL)

3. Ensure your JSON payload is properly formatted (for POST requests)

   • Use a JSON validator to check your payload
   • Ensure proper quotes around strings
   • Verify Content-Type header is set to application/json

4. Confirm that all required variables in your templates are being provided (channels with a custom template)

   • Check your notification templates to see which variables they use
   • Verify those variables are in your webhook request (query params or JSON body)
   • Remember that missing variables will render as empty strings

5. Check if the channel has active subscribers

   • Notifications are only sent if someone is subscribed to the channel
   • Verify your subscription in the app's channel list
   • Check that subscriptions haven't been accidentally removed

Notifications Rendering Incorrectly

1. Variable names don't match

   • Template uses {{server_name}} but webhook sends serverName
   • Variable names are case-sensitive and must match exactly
   • Check for typos in variable names

2. Nested data not accessible

   • Use dot notation: {{user.name}} or bracket notation: {{user["name"]}}
   • Verify the structure of your JSON matches your template expectations
   • Test with simple flat variables first, then add nesting

3. Special characters causing issues

   • URL-encode query parameters properly
   • Escape special JSON characters in POST bodies
   • Test with simple ASCII text first

Testing Your Integration

Use curl to test your webhook directly:

# Test with query parameters
curl "https://hook.echobell.one/t/<channel-token>?title=hello&body=working"

# Test with JSON body
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H "Content-Type: application/json" \
  -d '{"title": "hello", "body": "working"}'

You should receive a notification immediately if everything is configured correctly.

Still Having Issues?

If you've tried the above steps and still experiencing problems:

• Visit our Support Center for more troubleshooting guides
• Check if there are known issues or service status updates
• Contact us at echobell@weelone.com with:
  • Description of the problem
  • Steps you've tried
  • Example webhook URL (with token removed/redacted)
  • Sample request payload
  • Expected vs. actual behavior

Next Steps

Now that you understand webhook integration:

• Learn Template Syntax - Create dynamic, informative notifications
• Use Conditions - Filter notifications based on data
• Explore Integrations - Connect with tools you already use
• Set Up Grafana Alerts - Monitor infrastructure
• Configure GitHub Actions - Get CI/CD notifications
• Email Triggers - Alternative trigger method for email-based systems

Ready to integrate Echobell with your systems? Create your first channel and start receiving instant notifications!