Webhooks

• 1. Задайте адрес. Публичный https-адрес, на который Sofia отправит событие.
• 2. Выберите события. post.published и post.failed.
• 3. Зарегистрируйте его. POST /v1/webhooks: секрет подписи (whsec_…) показывается только в этом ответе.
• 4. Отправьте тест. POST /v1/webhooks/{id}/test отправляет событие webhook.test, подписанное так же, как остальные.

Полный запрос описан на вкладке API: Регистрация вебхука. Объявляются только публикации, созданные вашим приложением.

Всегда сначала отправляйте тест и сохраняйте полученное тело: это контракт, надёжнее любого описания. Sofia отправляет каждое событие через POST в формате JSON { id, type, createdAt, data } с заголовками Sofia-Event-Id, Sofia-Event-Type и Sofia-Signature.

• Проверяйте подпись. Sofia-Signature имеет вид t=<unix time>,v1=<hex>, где v1 — HMAC-SHA256 от <t>.<raw body> с вашим секретом. Вычисляйте его по необработанному телу и отклоняйте устаревшую метку времени.
• Быстро отвечайте `2xx`, а работу делайте потом: медленную конечную точку не отличить от неработающей.
• Будьте идемпотентны. Одно и то же событие может прийти дважды: дедуплицируйте по Sofia-Event-Id.

Адрес недоступен

Sofia вызывает со своих серверов: адрес должен быть публичным https. Перенаправление никогда не отслеживается, а 10 секунд без ответа считаются сбоем.

Адрес возвращает ошибку

Любой ответ, кроме 2xx, запускает повторную попытку через 1 минуту, 5 минут, 30 минут и 2 часа, всего до 5 попыток. Сначала посмотрите свои журналы, затем воспроизведите с помощью POST /v1/webhooks/{id}/test.

Публикация создана не вашим приложением

Вебхук объявляет только публикации, созданные вашим приложением; публикация, созданная в интерфейсе, его не запускает.

Вебхук сообщает, когда Sofia что-то сделала. Чтобы Sofia что-то сделала, используйте Sofia API, CLI sofia или сервер MCP (вкладки API и Agents) либо Сторонние интеграции.