Проверено 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-signature | t=<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 остается доступным. Существующие секреты подписи никогда не показываются снова.