Настройка вебхуков для клиентов
Зарегистрируйте HTTPS-адрес для поддерживаемых событий, защитите секрет подписи и изучайте историю доставок для диагностики ошибок.
- Подготовьте приёмникИспользуйте общедоступную конечную точку HTTPS, готовую принимать JSON.
- Подпишитесь на событияУкажите название конечной точки, URL и типы событий.
- Защитите подписьСохраните секрет, который показывается один раз, и проверяйте входящие запросы.
- Проверьте доставкиИспользуйте состояние и сведения об ответах для устранения проблем.
- Поддерживайте адрес в актуальном состоянииМеняйте секреты и отзывайте больше не нужные адреса.
Поддерживаемые события для клиентов
В форме доступны события завершения задания, выставления счёта и достижения порога квоты. Выбирайте только события, которые обрабатывает ваш приёмник. Конечные точки относятся к личному или выбранному контексту организации. Ими могут управлять владельцы и администраторы организации; участники могут только просматривать их. Вебхук отправляет уведомления, но сам не изменяет заказ или счёт.
- Откройте вебхуки в контексте нужной организации.
- Выберите хотя бы одно событие, которое поддерживает ваш приёмник.
- Для разных сред настройте отдельные конечные точки.
Регистрация общедоступного адреса
Создайте конечную точку, указав имя длиной от 2 до 120 символов, допустимый URL и одно или несколько перечисленных событий. Требуются HTTPS и общедоступное имя узла. Адреса localhost, внутренней сети и частные IP-адреса отклоняются, поэтому локальный адрес разработки не подойдёт. Отправляйте форму, когда приёмник уже умеет принимать JSON и возвращать успешный HTTP-ответ.
- Разместите приёмник по стабильному общедоступному адресу HTTPS.
- Укажите URL, понятное название и нужные события.
- Отправьте форму один раз и исправьте ошибки проверки, если они появятся.
Проверка подписанных сообщений
При создании секрет подписи показывается только один раз. Запрос содержит заголовки события, доставки, временной метки и HMAC-подписи, а также JSON с ID события, типом, временем создания и данными. Проверяйте подпись по временной метке и исходному телу запроса без изменений, задайте разумное окно допустимого времени и идемпотентно обрабатывайте повторные ID. Не помещайте секрет в журналы и сообщения поддержки.
- Сохраните секрет в защищённой конфигурации приёмника.
- Проверьте подпись по неизменённому телу запроса.
- Записывайте ID событий, чтобы не выполнять действие повторно.
История доставок
На странице показаны последние 50 доставок для всех ваших конечных точек. Успешные HTTP-ответы отмечаются как доставленные. Ошибки сервера и ограничения частоты запросов могут повлечь повторную попытку; остальные неуспешные ответы могут завершиться сразу, а число попыток ограничено. В истории указаны статус ответа и ограниченное по длине тело ответа или сообщение об ошибке. Событие может отсутствовать, если оно не происходило или конечная точка на него не подписана.
- Изучите событие, число попыток, состояние и последнюю ошибку.
- Исправьте доступность приёмника, его ответ или ограничение частоты запросов.
- Проверьте, что следующая доставка завершилась успешно.
Ротация секрета подписи
При ротации секрет конечной точки заменяется, и она снова становится активной. Приёмники, настроенные только со старым секретом, будут отклонять новые запросы. Подготовьте изменение конфигурации, выберите нужную строку конечной точки, выполните ротацию, сохраните новый секрет и оперативно разверните его. При утечке смените секрет немедленно и проверьте историю доставок на предмет подозрительной активности.
- Определите все экземпляры приёмника и подготовьте безопасное развёртывание.
- Смените секрет конечной точки и сохраните одноразово показанное значение.
- Убедитесь, что последующая ожидаемая доставка прошла успешно.
Замена и отзыв конечной точки
Клиент может создать, сменить секрет или отозвать конечную точку; изменить URL или набор событий нельзя. Чтобы изменить их, создайте замену, проверьте доставку нужных событий, затем отзовите прежнюю точку. После отзыва новые события не доставляются, а точка становится неактивной. Так следует поступать с устаревшими адресами или раскрытыми секретами; после действия проверьте список.
- Создайте замену с исправленным URL или набором событий.
- Убедитесь, что на новую точку успешно доставляется событие.
- Отзовите старую точку и проверьте, что она неактивна.
Часто задаваемые вопросы
Какие события доступны?
Завершение задания, выставление счёта и достижение порога квоты.
Можно использовать обычный HTTP?
Нет. Требуется общедоступный URL HTTPS.
Можно посмотреть секрет повторно?
Нет. Выполните ротацию конечной точки, чтобы получить новый секрет.
Почему доставка ожидает повтора?
Повтор может потребоваться из-за временной ошибки сервера или ограничения частоты запросов.
Почему доставка завершилась ошибкой?
Причину можно найти в ответе и истории повторных попыток.
Можно изменить конечную точку?
Нет. Создайте замену, проверьте её и отзовите прежнюю точку.