Platitun · API · Подписка на события · Задать адрес и события

Задать адрес и события

PUT /api/v1/hooks

Область ключа: hooks · изменяет данные, нужен заголовок Idempotency-Key

Первый вызов заводит подписку и возвращает секрет подписи ОДИН раз. Дальнейшие вызовы правят адрес и состав событий, а секрет НЕ меняют: у вас проверка подписи уже настроена, и менять секрет за вас — сломать её молча.

Адрес проверяется ПЕРЕД КАЖДОЙ отправкой, а не только при сохранении: имя, безобидное сегодня, к моменту отправки может указывать во внутреннюю сеть. Внутренние и служебные адреса не принимаются вовсе.

Правка адреса СНИМАЕТ паузу и обнуляет счётчик неудач: вы поправили именно то, из-за чего доставка встала.

Поля запроса

Поле	Тип	Что это
`url` обязательно	`string`	Куда стучаться. Только https и только публичный узел.
`events` обязательно	`array`	О чём стучаться. Пустой набор не принимается: подписка ни на что выглядела бы работающей и молчала.

Поля ответа

Поле	Тип	Что это
`secret`	`string\|null`	Секрет подписи — только при создании подписки. При правке пусто.
`events`	`array`	Набор, как его понял сервер: мусор и повторы отсеяны.

Поводы отказа

Отказ по правилам приходит как {"error":"rejected","refusal":{"kind":"…"}} с кодом 409. Общие для всех путей отказы — в разделе правил.

Код	Что случилось и что делать
`url`	Адрес доставки не годен: внутри отказа код причины — только https, только публичный узел, без имени и пароля внутри адреса.
`no_events`	Отметьте хотя бы одно событие: подписка ни на что выглядела бы работающей и молчала.
`vault_off`	Сейф площадки не настроен, и хранить секреты негде. Это наша беда, а не ваша: напишите в поддержку.

Рядом в этом разделе

GET /api/v1/hooks — Своя подписка на события
DELETE /api/v1/hooks — Отключить доставку
POST /api/v1/hooks/secret — Заменить секрет подписи
POST /api/v1/hooks/resume — Включить доставку снова
POST /api/v1/hooks/test — Пробное событие
GET /api/v1/hooks/deliveries — Журнал доставки
POST /api/v1/hooks/probe — Выдать адрес служебного приёмника
GET /api/v1/hooks/probe — Что принял служебный приёмник