Документация

Всё, что нужно для интеграции с Hooki

Quickstart

1. Регистрация и создание канала

Зарегистрируйтесь на hooki.ru — это займёт 30 секунд. После входа создайте свой первый канал в панели управления.

2. Получение API-ключа

В настройках канала создайте API-ключ. Ключ показывается один раз — сохраните его. Он понадобится для отправки уведомлений.

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

Используйте любой HTTP-клиент. Вот пример на curl:

curl -X POST https://hooki.ru/api/v1/notify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Привет, мир!",
    "body": "Моё первое уведомление через Hooki",
    "priority": "normal"
  }'

4. Установка приложения

Установите приложение Hooki на телефон (Android / iOS). Войдите с тем же аккаунтом — уведомления начнут приходить мгновенно.

5. Примеры на разных языках

Python:

import requests

requests.post("https://hooki.ru/api/v1/notify",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "Привет!",
        "body": "Уведомление из Python"
    }
)

JavaScript (Node.js / Browser):

await fetch("https://hooki.ru/api/v1/notify", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    title: "Привет!",
    body: "Уведомление из JavaScript"
  })
});

Go:

payload := strings.NewReader(`{"title":"Привет!","body":"Из Go"}`)
req, _ := http.NewRequest("POST", "https://hooki.ru/api/v1/notify", payload)
req.Header.Set("X-API-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(req)

PHP:

$ch = curl_init("https://hooki.ru/api/v1/notify");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: YOUR_API_KEY",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "title" => "Привет!",
        "body" => "Из PHP"
    ])
]);
curl_exec($ch);

API Reference

Аутентификация

Все запросы к API аутентифицируются через заголовок X-API-Key. Ключ создаётся в панели управления для каждого канала.

X-API-Key: hk_live_7f3a9b2c...

Базовый URL

https://hooki.ru/api/v1

POST /api/v1/notify

Отправка уведомления всем подписчикам канала.

Заголовки:

ЗаголовокЗначение
X-API-KeyAPI-ключ канала
Content-Typeapplication/json

Тело запроса:

ПолеТипОбязательноОписание
titlestringДаЗаголовок уведомления (до 200 символов)
bodystringНетТекст уведомления (до 4000 символов)
prioritystringНетcritical, normal (по умолчанию), low
image_urlstringНетURL изображения
buttonsarrayНетКнопки действий (до 3 штук)

Объект button:

ПолеТипОбязательноОписание
labelstringДаТекст кнопки (до 30 символов)
webhook_urlstringНетURL для webhook callback при нажатии
modestringНетsingle (по умолчанию) или independent

Ответ: 202 Accepted

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "accepted"
}

GET /api/v1/notifications/{id}/status

Статус доставки уведомления.

Ответ: 200 OK

{
  "notification_id": "...",
  "total": 5,
  "sent": 3,
  "pending": 2,
  "failed": 0
}

Каналы (CRUD)

Управление каналами через JWT-аутентификацию (панель управления).

МетодПутьОписание
POST/api/v1/channelsСоздание канала
GET/api/v1/channelsСписок каналов
GET/api/v1/channels/{id}Детали канала
PATCH/api/v1/channels/{id}Обновление канала
DELETE/api/v1/channels/{id}Удаление канала

Webhook формат

При нажатии кнопки Hooki отправляет POST-запрос на указанный webhook_url:

{
  "event": "action_pressed",
  "notification_id": "...",
  "button_label": "Открыть ворота",
  "user_id": "...",
  "pressed_at": "2025-01-15T10:30:00Z"
}

Retry-политика: 3 попытки с экспоненциальной задержкой (2, 4, 8 секунд).

Коды ошибок

КодОписание
400Невалидные данные запроса
401Отсутствует или невалидный API-ключ
403Нет доступа к ресурсу
404Ресурс не найден
409Конфликт (повторное действие в single mode)

Концепции

Каналы и подписки

Канал — это источник уведомлений. Создатель канала (owner) получает API-ключ для отправки уведомлений. Другие пользователи подписываются на канал и получают уведомления.

Подписаться можно двумя способами:

  • По приглашению — владелец создаёт invite-ссылку (с опциональным лимитом использований и сроком действия)
  • Публичный канал — если канал помечен как публичный, любой может подписаться через поиск

Приоритеты уведомлений

Каждое уведомление имеет приоритет, влияющий на отображение и звук:

ПриоритетОписаниеПоведение
criticalКритичныеПолноэкранное уведомление, громкий звук, игнорирует тихие часы
normalОбычныеСтандартный push, обычный звук
lowИнформационныеТихое уведомление, без звука

Режимы действий (Action Modes)

Кнопки действий могут работать в двух режимах:

  • single (по умолчанию) — кнопку может нажать только один человек. После нажатия она блокируется для остальных. Идеально для задач типа «кто первый — тот и выполняет».
  • independent — каждый подписчик может нажать кнопку независимо. Подходит для опросов или когда действие должен выполнить каждый.

Shared Actions — синхронизация

Когда кнопка в режиме single нажата одним пользователем:

  1. Кнопка мгновенно блокируется у всех подписчиков через WebSocket
  2. Все видят кто нажал и когда
  3. Webhook отправляется на сервер разработчика

Это позволяет координировать действия группы людей без конфликтов.

Webhook Callbacks

При нажатии кнопки с webhook_url Hooki отправляет POST-запрос на указанный адрес.

Retry-политика:

  • Максимум 3 попытки
  • Задержка между попытками: 2n секунд (2, 4, 8)
  • Успешный ответ: любой 2xx код
  • Timeout: 10 секунд на каждую попытку

Примеры интеграций

Мониторинг сервера (Bash + Cron)

Проверка доступности сайта каждые 5 минут:

#!/bin/bash
# check_site.sh
URL="https://mysite.ru"
API_KEY="hk_live_YOUR_KEY"

if ! curl -sf "$URL" > /dev/null; then
  curl -X POST https://hooki.ru/api/v1/notify \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"title\": \"Сайт недоступен!\",
      \"body\": \"$URL не отвечает\",
      \"priority\": \"critical\",
      \"buttons\": [
        {\"label\": \"Перезапустить\", \"webhook_url\": \"https://myserver.ru/restart\"}
      ]
    }"
fi
# crontab -e
*/5 * * * * /opt/scripts/check_site.sh

CI/CD (GitHub Actions)

Уведомление при падении билда:

# .github/workflows/notify.yml
name: Notify on failure
on:
  workflow_run:
    workflows: ["Build"]
    types: [completed]

jobs:
  notify:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -X POST https://hooki.ru/api/v1/notify \
            -H "X-API-Key: ${{ secrets.HOOKI_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "title": "Билд упал",
              "body": "Репозиторий: ${{ github.repository }}",
              "priority": "critical",
              "buttons": [
                {"label": "Перезапустить", "webhook_url": "https://api.github.com/..."}
              ]
            }'

Умный дом (ESP32 / Arduino)

Отправка уведомления при срабатывании датчика:

// Arduino / ESP32
#include <HTTPClient.h>

void sendNotification() {
  HTTPClient http;
  http.begin("https://hooki.ru/api/v1/notify");
  http.addHeader("X-API-Key", "hk_live_YOUR_KEY");
  http.addHeader("Content-Type", "application/json");

  String body = "{\"title\":\"Движение у ворот\","
    "\"priority\":\"critical\","
    "\"buttons\":[{\"label\":\"Открыть\","
    "\"webhook_url\":\"https://myiot.ru/gate/open\"}]}";

  http.POST(body);
  http.end();
}

Python-бот

Уведомление о новых заказах из интернет-магазина:

import requests

def notify_new_order(order):
    requests.post("https://hooki.ru/api/v1/notify",
        headers={"X-API-Key": HOOKI_API_KEY},
        json={
            "title": f"Новый заказ #{order.id}",
            "body": f"{order.customer}, {order.total} ₽",
            "priority": "normal",
            "buttons": [
                {"label": "Подтвердить",
                 "webhook_url": f"https://shop.ru/orders/{order.id}/confirm"},
                {"label": "Отклонить",
                 "webhook_url": f"https://shop.ru/orders/{order.id}/reject"}
            ]
        }
    )

Node.js приложение

Express middleware для уведомления об ошибках:

// errorNotifier.js
const HOOKI_KEY = process.env.HOOKI_API_KEY;

async function errorHandler(err, req, res, next) {
  await fetch("https://hooki.ru/api/v1/notify", {
    method: "POST",
    headers: {
      "X-API-Key": HOOKI_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      title: `Ошибка: ${err.message}`,
      body: `${req.method} ${req.path}`,
      priority: "critical"
    })
  });
  next(err);
}

module.exports = errorHandler;