Direct Notifications - Personal API Keys for Instant Alerts

Direct notifications let you send personal alerts via a simple webhook URL — no channel setup, no templates, no subscribers. Just create a key, call the URL, and get notified instantly on your device.

What is Direct?

Channels are great for structured, templated notifications that can be shared with others. But sometimes you just want a quick, personal notification — a build finished, a script completed, a sensor triggered. Direct is designed for exactly that.

With Direct, you get a personal API key that maps to a unique webhook URL. When you call that URL with a title and body, a notification is sent directly to you. No channel configuration needed.

When to Use Direct vs. Channels

Getting Started

1. Create a Direct Key

In the Echobell app, tap Direct at the top of your channels list. Then tap Create to generate a new Direct key. Give it a descriptive name (e.g., "Build Server", "Home Lab", "Trading Bot").

2. Copy the Webhook URL

Each Direct key has a unique webhook URL in this format:

https://hook.echobell.one/d/{your-key-token}

You can find and copy this URL from the Direct key detail view in the app. The token is hidden by default for security — tap to reveal it.

3. Send a Notification

Call the webhook URL with a JSON body containing title and body:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Build Complete",
  "body": "Project X built successfully in 3m 42s"
}

That's it — you'll receive a notification immediately.

Making Requests

POST Request (Recommended)

Send a JSON body with your notification content:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Deployment Status",
  "body": "v2.1.0 deployed to production",
  "externalLink": "https://dashboard.example.com/deploys/latest"
}

GET Request

You can also pass parameters via query string:

GET https://hook.echobell.one/d/YOUR_KEY_TOKEN?title=Alert&body=CPU+at+95%25

POST Only

Each direct key has its own POST Only setting in the Echobell app. It is off by default.

When it is on, only POST can trigger that key. A GET to its 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.

The setting is per key, so you can keep a GET-friendly key for shell one-liners and a POST-only key for URLs that get pasted into chat or wiki pages.

Request Fields

All field names are case-insensitive — title, Title, and TITLE are all treated the same way, whether passed via JSON body or query string.

Notification Types

You can control the urgency level of Direct notifications using the notificationType field:

Example with notification type:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Server Down",
  "body": "Production server is unresponsive",
  "notificationType": "calling"
}

Response Format

A successful request returns:

{
  "success": true,
  "message": "Notification triggered successfully."
}

If the key is invalid or not found (note this still returns HTTP 200):

{
  "success": false,
  "message": "Direct key not found."
}

Managing Direct Keys

Multiple Keys

You can create multiple Direct keys for different purposes:

• "CI Server" — for build and deployment notifications
• "Home Automation" — for IoT sensor alerts
• "Cron Jobs" — for scheduled task results
• "Trading Bot" — for market alerts

Each key has its own independent webhook URL. Notification records are automatically associated with the key that triggered them, so you can easily identify which service sent each notification.

Reset Token

If a key's webhook URL is compromised, you can reset the token from the key's detail view. This generates a new URL and immediately invalidates the old one. Update any scripts or services using the old URL.

Delete a Key

Deleting a Direct key permanently invalidates its webhook URL. Any requests to the old URL will fail.

Common Use Cases

Shell Scripts

# Notify when a long-running task finishes
./run-migration.sh && \
curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Migration Complete", "body": "Database migration finished successfully"}'

Cron Jobs

# In crontab: notify on backup completion
0 2 * * * /usr/local/bin/backup.sh && curl -s -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN -H "Content-Type: application/json" -d '{"title": "Backup Done", "body": "Nightly backup completed"}'

Python

import requests

requests.post(
    "https://hook.echobell.one/d/YOUR_KEY_TOKEN",
    json={
        "title": "Training Complete",
        "body": f"Model accuracy: {accuracy:.2%}",
        "externalLink": "https://wandb.ai/runs/abc123"
    }
)

Node.js

await fetch("https://hook.echobell.one/d/YOUR_KEY_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Deploy Complete",
    body: `Version ${version} deployed to production`,
  }),
});

GitHub Actions

- name: Notify via Echobell Direct
  if: always()
  env:
    ECHOBELL_DIRECT_URL: ${{ secrets.ECHOBELL_DIRECT_URL }}
  run: |
    curl -X POST "$ECHOBELL_DIRECT_URL" \
      -H "Content-Type: application/json" \
      -d '{"title": "Build ${{ job.status }}", "body": "${{ github.repository }} @ ${{ github.sha }}"}'

Best Practices

Security

• Treat Direct key URLs as secrets — anyone with the URL can send you notifications
• Use environment variables to store key tokens in scripts and CI/CD
• Reset tokens immediately if you suspect a key has been compromised
• Create separate keys for different services so you can revoke individually

Organization

• Name keys descriptively — you'll thank yourself when managing multiple keys
• Use one key per service — makes it easy to identify notification sources and revoke access
• Delete unused keys — reduce your attack surface

Error Handling

When integrating Direct into your scripts, branch on the JSON success field rather than the HTTP status:

• 200 OK: The request was received. Check the JSON body: success: true means the notification was triggered; success: false means it wasn't. An unknown or reset Direct key returns HTTP 200 with { "success": false, "message": "Direct key not found." } — it is not a 404.
• 400 Bad Request: The key token is the wrong length. Fix the URL.
• 405 Method Not Allowed: The key has POST Only turned on and the request wasn't a POST. Switch the caller to POST, or turn the setting off.

Echobell does not rate-limit Direct calls, so there is no 429 response.

Privacy and Security

What Gets Stored

• On Our Servers:

  • Direct key metadata (name, hashed token, owner)
  • Request payload is temporarily processed and stored for delivery

• On Your Device:

  • Notification content (title, body)
  • Trigger history and timestamps
  • External links

What Doesn't Get Stored

• We don't permanently retain request payloads after delivery
• We don't analyze notification content
• We don't share your data with third parties

Troubleshooting

Not Receiving Notifications

1. Verify the webhook URL — copy it directly from the app, check for extra spaces
2. Check the key still exists — it may have been deleted or token reset
3. Ensure notification permissions — the Echobell app needs notification permission on your device
4. Test with curl — rule out issues with your HTTP client:

   curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
     -H "Content-Type: application/json" \
     -d '{"title": "Test", "body": "Hello from Direct"}'

Request Errors

• JSON parse error: Ensure Content-Type: application/json header is set and body is valid JSON
• Key not found: A "success": false body with "Direct key not found." means the token was reset or the key deleted (the HTTP status is still 200)

Still Having Issues?

• Visit our Support Center for more help
• Contact us at echobell@weelone.com with:
  • Description of the problem
  • Example request (with token redacted)
  • Expected vs. actual behavior

Next Steps

• Webhook Integration — For shared, templated notifications with channels
• Template Syntax — Learn about channel notification templates
• Email Triggers — Trigger notifications via email
• Explore Integrations — Connect with tools you already use