AiVideoEditor
Начните бесплатно
Меню

Проверено 2026-11-11 · версия API 2026-11-09 · Читать Markdown

Клиентские вебхуки

Доставка исходящих событий для вашего рабочего пространства. Зарегистрируйте HTTPS-эндпоинт, проверьте одноразовый секрет подписи и получайте подписанные события с ограниченными повторами.

Регистрация эндпоинта

curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
  • Секрет подписи (whsec_…) возвращается один раз: в первом успешном ответе на создание. Сохраните его; идемпотентный повтор того же создания возвращает эндпоинт без секрета, и его нельзя показать снова.
  • Назначения должны быть HTTPS, публично разрешаемыми и без встроенных учетных данных. Запросы к приватным, loopback, link-local (включая облачные метаданные), unique-local и multicast-адресам отклоняются до установления любого соединения, и редиректы никогда не отслеживаются.
  • Регистрация ставит в очередь адресное событие webhook.verification для этого эндпоинта независимо от его фильтра eventTypes. Обычные события идут только после того, как ваш эндпоинт ответит на проверку с 2xx.

Проверка доставок

Каждый запрос несет:

ЗаголовокЗначение
x-publisher-event-idСтабильный ID события: одинаковый при повторах и воспроизведениях
x-publisher-event-typeТип события, например post.published
x-publisher-timestampСекунды Unix
x-publisher-signaturet=<ts>,v1=<hex>

Подпись — это HMAC-SHA256 над ${t}.${event_id}.${raw_body} с вашим секретом подписи. Проверяйте с допуском ±300 секунд и отклоняйте воспроизведения вне этого допуска. Пример на Node:

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

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Всегда проверяйте сырое (raw) тело запроса до парсинга.

Конверт события

{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}

Начальный каталог событий (расширяемый; eventTypes фильтрует при регистрации):

  • webhook.verification: полезная нагрузка-задание; ответьте 2xx, чтобы активировать эндпоинт
  • post.published: одно назначение подтверждено нативной квитанцией
  • delivery.failed: одно назначение окончательно завершилось сбоем
  • delivery.requires_action: требуется согласие/переподключение/поздняя проверка

Агрегированные результаты постов (post.partially_published, post.failed) пока не отправляются; они документируются здесь только когда появится их производитель, так что не полагайтесь на них. Подписывайтесь на события по назначениям выше и выводите состояние партии из результатов доставок поста.

Повторы, воспроизведение и отключение

  • Попытки: немедленно, затем +1m, +5m, +30m, +2h, +8h. Повторы используют тот же ID события и побайтово идентичное тело, поэтому вы можете безопасно дедуплицировать.
  • 2xx = доставлено. 429/5xx/таймауты повторяются. Другие 4xx окончательно завершаются сбоем для этого события (исправьте эндпоинт, затем воспроизведите).
  • 410 Gone отключает эндпоинт: дальнейшие события в него не ставятся в очередь.
  • Авторизованный оператором повтор через внутренний сервис вебхуков повторно отправляет событие с его исходным ID. Активно занятая выполняющаяся попытка никогда не отзывается принудительно; повтор сообщает, что событие занято, и его можно вскоре повторить.

Операционные заметки

  • Диагностика доставки хранит только безопасные коды результатов: никогда ваш секрет, подписи, заголовки запросов или тела ответов. Полезные нагрузки дополнительно очищаются: секреты провайдеров/OAuth и presign-URL медиа удаляются до того, как что-либо ставится в очередь.
  • Эндпоинты ограничены рабочим пространством: обладание UUID эндпоинта из другого рабочего пространства ничего не дает.
  • Доставка происходит как минимум один раз на каждое принятое событие; дедуплицируйте по x-publisher-event-id.

Доступность инструментов разработчика

Страница Developers перечисляет ключи API рабочего пространства и эндпоинты вебхуков независимо от конфигурации шифрования секрета подписи. Создание вебхука требует корректной конфигурации шифрования сервера; попросите оператора развертывания устранить предупреждение конфигурации. Управление ключами API остается доступным. Существующие секреты подписи никогда не показываются снова.