Автоматизация

Вебхуки

Получайте вызов на свой сервер, когда задача закончилась или телефону нужно внимание.

Добавить вебхук

В панели: Настройки → Подключения → События → Вебхуки. Или через API:

Подписка

POST /v1/webhooks
{"url": "https://example.com/clousd", "events": ["run.completed", "run.failed"], "description": "orders bot"}
# → 201 {"webhook": {"id": "wh_3c1a", …}, "secret": "whsec_…"}   the secret is shown once

Пустой events означает все события. У ключа может быть до десяти вебхуков, у каждого свой секрет. POST /v1/webhooks/{id}/rotate выдаёт новый секрет, /toggle приостанавливает доставку, /test сразу отправляет тестовое событие, GET …/deliveries показывает последние доставки с кодом ответа и временем.

События

Событие	Когда
run.completed	Задача выполнена; в теле — запуск с ответом.
run.failed	Задачу не удалось выполнить; в теле — причина.
run.cancelled	Задачу остановили.
run.waiting	Задача остановилась, чтобы задать вопрос или попросить разрешение.
device.problem	Проверка состояния телефона не прошла.
device.resolved	Проблема устранена.

Проверка подписи

Каждая доставка — это POST с телом в JSON и заголовком X-Clousd-Signature: t=<unix time>,v1=<hex>, где hex — HMAC-SHA256 от "<t>.<raw body>" с секретом вебхука в качестве ключа. Отклоняйте старые метки времени, чтобы отсечь повторную отправку.

Python

import hashlib, hmac, time

def valid(body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    mac = hmac.new(secret.encode(), t.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, sig)

Повторы

Каждое событие отправляется до четырёх раз: сразу, через 30 секунд, через 5 минут и через 30 минут. Чтобы подтвердить получение, ответьте любым 2xx. Тело — {"id", "type", "created", "data"}, тот же id приходит в X-Clousd-Event-Id: если повтор дошёл до вас после медленного успешного ответа, пропустите id, который уже обработали. После 20 неудачных доставок подряд вебхук сам встаёт на паузу; включите его снова в панели или через /toggle.