---
title: Webhook Integration - Complete Guide to HTTP Triggers
sidebarTitle: Webhooks
description: "Integrate Echobell webhooks: HTTP methods, variables, templates, headers, and real-world examples for instant mobile alerts."
---

# Webhook Integration

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.

<Callout type="info">
  **Used Direct keys?** Direct keys are now channels. Each of your keys was
  turned into a channel with the same name, and its old
  `https://hook.echobell.one/d/…` URL keeps working exactly as before, so your
  scripts don't need to change. New integrations can use the channel's `/t/`
  webhook URL from the app, which takes the same fields. On the `/t/` URL,
  `notificationType` can only lower the level you subscribed at (see
  [Notification Level](#notification-level)), so if a script asks for
  `calling`, subscribe to the channel at Calling.
</Callout>

## 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.

### What is a webhook endpoint?

A webhook endpoint is the URL that receives webhook requests: the address you paste into the sending service so it knows where to deliver each event. The sender makes an HTTP request (usually a POST with a JSON body) to that URL, and the endpoint answers with a status code such as `200 OK` to confirm it got the event.

In Echobell, every channel has its own webhook endpoint, for example `https://hook.echobell.one/t/<channel-token>`. Paste it into Grafana, GitHub Actions, TradingView or any other service as the webhook URL, and each request to it becomes a notification for the channel's subscribers. The token in the URL is what identifies the channel, so treat the endpoint like a password.

### 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](#custom-templates) 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.

| Field | Description |
|---|---|
| `title` | Notification title. Defaults to the channel name. |
| `body` | Notification body. Defaults to empty. |
| `externalLink` | A link shown with the notification record. Useful for pointing at a dashboard, log or pull request. |
| `notificationType` | `active`, `time-sensitive` or `calling`. Can only lower the level each subscriber chose — see [Notification Level](#notification-level). |

### GET Request

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

### POST Request

Send a JSON body:

```http
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:

```bash
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:

```json
{
  "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:

```json
{
  "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](/docs/notification) 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:

```bash
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:

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

Or in a JSON body:

```http
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](/docs/template) for the full syntax and [Conditions](/docs/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.

```http
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](/docs/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](/docs/developer/prometheus) or [Grafana](/docs/developer/grafana)
- **Uptime Monitoring**: Website and service availability alerts from [Uptime Kuma](/docs/developer/uptime-kuma) or [UptimeRobot](/docs/developer/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](/docs/developer/github) 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](/docs/developer/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](/docs/trader/tradingview)
- **Portfolio Monitoring**: Position changes, margin calls, account balances
- **Economic Events**: News releases, earning reports, market sentiment changes

See our [integration guides](/docs/features) 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](#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](/docs/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](/docs) 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](/docs/template) 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](/docs/support).

## 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:

```bash
# 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](/docs/support) 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](/docs/template)** - Create dynamic, informative notifications
- **[Use Conditions](/docs/conditions)** - Filter notifications based on data
- **[Explore Integrations](/docs/features)** - Connect with tools you already use
- **[Set Up Grafana Alerts](/docs/developer/grafana)** - Monitor infrastructure
- **[Configure GitHub Actions](/docs/developer/github)** - Get CI/CD notifications
- **[Email Triggers](/docs/email-trigger)** - Alternative trigger method for email-based systems

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