Webhooks

Получить ключ API

Эндпоинты

POST/v1/webhooksGET/v1/webhooksDELETE/v1/webhooks/{id}POST/v1/webhooks/{id}/test

Регистрация webhook

Зарегистрируйте публичный https-адрес и нужные события. Секрет подписи (whsec_…) показывается только в этом ответе. У приложения может быть до 10 webhook.

bash
curl -X POST https://api.sofia-post.com/api/v1/webhooks \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://app.example.com/hooks/sofia","events":["post.published","post.failed"]}'

События

Событиеdata
post.publishedpostId, establishmentId, platform, publishedAt, permalink
post.failedpostId, establishmentId, platform, error
webhook.testwebhookId

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> с вашим секретом. Проверяйте её по необработанному телу и отклоняйте старую метку времени:

javascript
import { createHmac, timingSafeEqual } from 'node:crypto';

const isSignedBySofia = (header, rawBody, secret) => {
  const parts = Object.fromEntries(
    (header ?? '').split(',').map((part) => part.trim().split('=', 2)),
  );
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || typeof parts.v1 !== 'string') return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1, 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
};

Доставка и повторы

  • Ответ 2xx означает доставку события. Любой другой ответ, перенаправление (оно никогда не выполняется) или 10 секунд без ответа вызывают повтор через 1 минуту, 5 минут, 30 минут и 2 часа, не более 5 попыток.
  • Одно и то же событие может прийти дважды: дедуплицируйте по Sofia-Event-Id.
  • Отвечайте быстро, а событие обрабатывайте потом.

POST /v1/webhooks/{id}/test отправляет событие webhook.test, подписанное так же, как остальные.