---
title: Прямые уведомления - персональные API-ключи для мгновенных оповещений
sidebarTitle: Прямые уведомления
description: Отправляйте уведомления напрямую с персональным API-ключом - без настройки канала. Создавайте прямые ключи и запускайте мгновенные оповещения с заголовком, текстом и ссылками.
---

# Прямые уведомления

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

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

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

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

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

| | Прямые уведомления | Каналы |
|---|---|---|
| **Настройка** | Создать ключ, использовать URL | Создать канал, настроить шаблоны |
| **Аудитория** | Только вы | Любой, кто подпишется |
| **Шаблоны** | Нет — заголовок и текст задаются в каждом запросе | Настраиваемые шаблоны с переменными |
| **Условия** | Нет | Поддерживается условная доставка |
| **Подходит для** | Личных скриптов, быстрых оповещений, автоматизации | Общих оповещений, структурированных процессов |

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

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

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

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

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

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

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

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

Вызовите URL вебхука с телом JSON, содержащим `title` и `body`:

```http
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 с содержимым уведомления:

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

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

```http
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`, и уведомление не отправляется:

```json
{
  "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 или в строке запроса.

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| `title` | string | Нет | Заголовок уведомления. Если не указан, используется «Direct Notification». |
| `body` | string | Нет | Текст уведомления. |
| `externalLink` | string | Нет | Кликабельная ссылка, которая показывается в записи уведомления. |
| `notificationType` | string | Нет | Уровень срочности уведомления. Принимает `active`, `time-sensitive` или `calling`. По умолчанию `active`. См. [Типы уведомлений](#типы-уведомлений). |

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

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

| Тип | Описание |
|---|---|
| `active` | Обычное уведомление, доставляется в стандартном режиме. Значение по умолчанию. |
| `time-sensitive` | Уведомление с высоким приоритетом, способное пробиться через режимы фокусирования. |
| `calling` | Оповещение в виде звонка для критических ситуаций. **Требуется активная подписка Premium.** Без Premium используется `time-sensitive`. |

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

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

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

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

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

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

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

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

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

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

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

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

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

### Сброс токена

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

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

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

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

### Скрипты shell

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

```bash
# В 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

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

```javascript
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

```yaml
- 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`. Переведите вызывающую сторону на `POST` или отключите настройку.

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

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

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

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

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

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

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

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

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

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

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

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

## Что дальше

- **[Интеграция вебхуков](/docs/webhook)** — общие уведомления по шаблону через каналы
- **[Синтаксис шаблонов](/docs/template)** — как устроены шаблоны уведомлений в каналах
- **[Email-триггеры](/docs/email-trigger)** — запуск уведомлений по электронной почте
- **[Изучите интеграции](/docs/features)** — подключение к инструментам, которыми вы уже пользуетесь