Золотенков
Выпустить ключ

Завести подписку на события

POST https://mrp.zolotenkov.ru/api/external/v1/webhook-subscriptions

Требуемое право ключа: write:webhook.subscription.create

Заводит подписку и **единственный раз** показывает ее секрет подписи (whsec_…): им проверяется заголовок X-Zolotenkov-Signature каждого уведомления. Восстановить секрет нельзя — потерянный меняется только заведением новой подписки.

Адрес получателя проверяется сразу: https, публичный адрес, порт 443 или выше 1024. Адрес, записанный именем узла, принимается, но имя разрешается в адрес перед каждой отправкой, и уведомление во внутреннюю сеть не уйдет — причина будет видна в журнале доставок.

Обязателен Idempotency-Key: повтор с тем же ключом вернет прежний ответ вместе с прежним секретом и второй подписки не заведет.

Заголовки

  • Idempotency-Key строка обязателен

    Обязателен, до 200 символов. Повтор с тем же ключом возвращает прежний ответ и второй подписки не заводит.

Тело запроса

Формат — application/json.

  • description строка необязателен может быть пустым

    Свободная строка «куда это уходит», до 255 символов.

  • events массив строк обязателен

    Типы событий. Хотя бы один; неизвестный тип отвечает 400, а не отбрасывается молча — иначе клиент прочитал бы отказ как «подписался».

  • url строка обязателен

    Адрес получателя: только https, только публичный адрес в интернете, порт 443 или выше 1024. Имя пользователя и пароль в адресе не принимаются — для подтверждения отправителя есть секрет подписи.

Ответы

  • 201 Подписка заведена. Поле secret показывается только здесь
  • 400 Недопустимый адрес получателя, пустой или неизвестный набор событий, слишком длинное описание
  • 401 Ключ не передан, недействителен или отозван
  • 403 У ключа нет права write:webhook.subscription.create
  • 409 Idempotency-Key повторен с другим телом
  • 422 Достигнут предел подписок клиента
  • 429 Превышена частота обращений. Задержка до повтора — в заголовке Retry-After