Прямые уведомления - персональные API-ключи для мгновенных оповещений

Прямые уведомления позволяют отправлять личные оповещения через обычный URL вебхука — без настройки канала, шаблонов и подписчиков. Достаточно создать ключ, вызвать URL и сразу получить уведомление на своём устройстве.

Что такое прямые уведомления?

Каналы хорошо подходят для структурированных уведомлений по шаблону, которыми можно поделиться с другими. Но иногда нужно просто быстрое личное уведомление: сборка завершилась, скрипт отработал, сработал датчик. Прямые уведомления сделаны именно для этого.

В этом режиме вы получаете персональный API-ключ, которому соответствует уникальный URL вебхука. Когда вы вызываете этот URL с заголовком и текстом, уведомление отправляется напрямую вам. Настраивать канал не нужно.

Когда использовать прямые уведомления, а когда каналы

Начало работы

1. Создайте прямой ключ

В приложении Echobell нажмите Прямые уведомления вверху списка каналов. Затем нажмите Создать, чтобы сгенерировать новый прямой ключ. Дайте ему понятное имя (например, «Сервер сборки», «Домашняя лаборатория», «Торговый бот»).

2. Скопируйте URL вебхука

У каждого прямого ключа есть уникальный URL вебхука такого вида:

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

Найти и скопировать этот URL можно на экране сведений о прямом ключе в приложении. Токен по умолчанию скрыт из соображений безопасности — нажмите на него, чтобы показать.

3. Отправьте уведомление

Вызовите URL вебхука с телом JSON, содержащим title и 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"
}

Готово — уведомление придёт сразу же.

Отправка запросов

POST-запрос (рекомендуется)

Отправьте тело JSON с содержимым уведомления:

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-запрос

Параметры можно передать и в строке запроса:

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

Только POST

У каждого прямого ключа в приложении Echobell есть собственная настройка Только POST. По умолчанию она выключена.

Когда она включена, запустить такой ключ можно только запросом POST. Запрос GET к его URL вебхука отклоняется с 405 Method Not Allowed, и уведомление не отправляется:

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

Запросов HEAD это не касается: они отвечают 200 и никогда не запускают уведомление независимо от того, включена настройка «Только POST» или нет.

Настройка действует на уровне ключа, поэтому вы можете держать один ключ с разрешённым GET для однострочников в shell и отдельный ключ только для POST — для URL, которые попадают в чаты или на вики-страницы.

Поля запроса

Регистр в именах полей не учитывается — title, Title и TITLE обрабатываются одинаково, переданы ли они в теле JSON или в строке запроса.

Типы уведомлений

Уровнем срочности прямых уведомлений можно управлять через поле notificationType:

Пример с указанием типа уведомления:

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

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

Формат ответа

Успешный запрос возвращает:

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

Если ключ недействителен или не найден (обратите внимание: HTTP-статус при этом всё равно 200):

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

Управление прямыми ключами

Несколько ключей

Вы можете создать несколько прямых ключей для разных задач:

• «CI-сервер» — для уведомлений о сборках и развёртываниях
• «Домашняя автоматизация» — для оповещений от IoT-датчиков
• «Cron-задачи» — для результатов запланированных задач
• «Торговый бот» — для рыночных оповещений

У каждого ключа свой независимый URL вебхука. Записи уведомлений автоматически связываются с ключом, который их запустил, поэтому легко понять, какой сервис прислал каждое уведомление.

Сброс токена

Если URL вебхука скомпрометирован, вы можете сбросить токен на экране сведений о ключе. При этом создаётся новый URL, а старый сразу перестаёт работать. Обновите скрипты и сервисы, которые используют старый URL.

Удаление ключа

Удаление прямого ключа навсегда делает его URL вебхука недействительным. Любые запросы к старому URL будут завершаться ошибкой.

Типичные сценарии

Скрипты shell

# Уведомить о завершении долгой задачи
./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-задачи

# В crontab: уведомление о завершении резервного копирования
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 }}"}'

Рекомендации

Безопасность

• Считайте URL прямых ключей секретами — любой, у кого есть URL, сможет отправлять вам уведомления
• Используйте переменные окружения для хранения токенов в скриптах и CI/CD
• Сбрасывайте токен сразу же, как только заподозрите, что ключ скомпрометирован
• Создавайте отдельные ключи для разных сервисов, чтобы отзывать их по одному

Организация

• Давайте ключам понятные имена — это окупится, когда ключей станет много
• Заводите по одному ключу на сервис — так проще определить источник уведомления и отозвать доступ
• Удаляйте неиспользуемые ключи — это уменьшает поверхность атаки

Обработка ошибок

Встраивая прямые уведомления в скрипты, ориентируйтесь на поле success в JSON, а не на HTTP-статус:

• 200 OK: запрос принят. Проверьте тело JSON: success: true означает, что уведомление запущено, success: false — что нет. Неизвестный или сброшенный прямой ключ возвращает HTTP 200 с { "success": false, "message": "Direct key not found." } — это не 404.
• 400 Bad Request: неверная длина токена ключа. Исправьте URL.
• 405 Method Not Allowed: у ключа включена настройка Только POST, а запрос был не POST. Переведите вызывающую сторону на POST или отключите настройку.

Echobell не ограничивает частоту вызовов прямых уведомлений, поэтому ответа 429 не бывает.

Конфиденциальность и безопасность

Что сохраняется

• На наших серверах:

  • Метаданные прямого ключа (имя, хешированный токен, владелец)
  • Тело запроса временно обрабатывается и хранится для доставки

• На вашем устройстве:

  • Содержимое уведомления (заголовок, текст)
  • История запусков и отметки времени
  • Внешние ссылки

Что не сохраняется

• Мы не храним тела запросов после доставки
• Мы не анализируем содержимое уведомлений
• Мы не передаём ваши данные третьим лицам

Устранение неполадок

Уведомления не приходят

1. Проверьте URL вебхука — скопируйте его прямо из приложения и убедитесь, что нет лишних пробелов
2. Убедитесь, что ключ ещё существует — его могли удалить или сбросить токен
3. Проверьте разрешения на уведомления — приложению Echobell нужно разрешение на уведомления на вашем устройстве
4. Проверьте через curl — чтобы исключить проблемы с вашим HTTP-клиентом:

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

Ошибки запроса

• Ошибка разбора JSON: убедитесь, что задан заголовок Content-Type: application/json, а тело запроса — корректный JSON
• Ключ не найден: тело с "success": false и "Direct key not found." означает, что токен сброшен или ключ удалён (HTTP-статус при этом остаётся 200)

Проблема осталась?

• Загляните в центр поддержки за дополнительной помощью
• Напишите нам на echobell@weelone.com и укажите:
  • Описание проблемы
  • Пример запроса (со скрытым токеном)
  • Ожидаемое и фактическое поведение

Что дальше

• Интеграция вебхуков — общие уведомления по шаблону через каналы
• Синтаксис шаблонов — как устроены шаблоны уведомлений в каналах
• Email-триггеры — запуск уведомлений по электронной почте
• Изучите интеграции — подключение к инструментам, которыми вы уже пользуетесь