АвтоматизацияWebhooks
Назад к Sofia

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

Webhooks

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

Вебхук — это HTTP-вызов, который Sofia совершает, когда публикация вышла или не удалась. Используйте его, чтобы перенести контент в таблицу, уведомить мессенджер или запустить сценарий в Zapier или n8n.

Как добавить

  • 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) либо Сторонние интеграции.

Эта страница была полезной?