--- metadata: - name: generator content: Diplodoc Platform v5.54.2 alternate: - https://yandex.ru/dev/kit/ru/openapi/Vebhuki/index.md - href: ru/openapi/Vebhuki/index.md type: text/markdown title: Markdown version - href: ../../llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/kit/ru/llms.txt # Вебхуки Управление вебхуками магазина. ## Структура payload При наступлении события система отправляет HTTP POST-запрос на зарегистрированный URL с JSON-телом. Конкретный вариант определяется значением поля `event`: | `event` | Схема payload | Описание | |---------------------------------|----------------------------------------|---------------------------------------| | `ORDER_STATUS_CHANGED` | `WebhookOrderStatusChangedPayload` | Изменение статуса заказа | | `ORDER_PAYMENT_STATUS_CHANGED` | `WebhookOrderPaymentStatusChangedPayload` | Изменение статуса оплаты заказа | | `ORDER_DELIVERY_STATUS_CHANGED` | `WebhookOrderDeliveryStatusChangedPayload` | Изменение статуса доставки заказа | | `WEBHOOK_VALIDATE` | `WebhookValidatePayload` | Запрос валидации URL при активации | ### Поля payload | Поле | Тип | Обязательное | Описание | |---------------|-----------------------|:------------:|-------------------------------------------------------------------------------| | `event_id` | `string (uuid)` | ✓ | Уникальный ID события. Используется для идемпотентной обработки. | | `event` | `string (enum)` | ✓ | Тип события: `ORDER_STATUS_CHANGED`, `ORDER_PAYMENT_STATUS_CHANGED`, `ORDER_DELIVERY_STATUS_CHANGED` или `WEBHOOK_VALIDATE`(при вызове `POST /v1/webhooks/{webhook_id}/validate?activate=true`) | | `occurred_at` | `string (date-time)` | ✓ | Время возникновения события | | `data` | `object` | | Данные события | ### Поля `data` для `ORDER_STATUS_CHANGED` | Поле | Тип | Обязательное | Описание | |--------------|-----------------|:------------:|----------------------------------| | `order_id` | `string (uuid)` | ✓ | ID заказа | | `new_status` | `OrderStatus` | ✓ | Новый статус заказа. Смотрите в разделе `Заказы` | ### Поля `data` для `ORDER_PAYMENT_STATUS_CHANGED` | Поле | Тип | Обязательное | Описание | |----------------------|-----------------|:------------:|-------------------------------------| | `order_id` | `string (uuid)` | ✓ | ID заказа | | `new_payment_status` | `PaymentStatus` | ✓ | Новый статус оплаты. Смотрите в разделе `Заказы` | ### Поля `data` для `ORDER_DELIVERY_STATUS_CHANGED` | Поле | Тип | Обязательное | Описание | |-----------------------|------------------|:------------:|--------------------------------------| | `order_id` | `string (uuid)` | ✓ | ID заказа | | `chunk_id` | `integer` | ✓ | ID части доставки заказа (заказ может иметь несколько отправлений) | | `new_delivery_status` | `DeliveryStatus` | ✓ | Новый статус доставки. Смотрите в разделе `Заказы` | Пример payload для `ORDER_STATUS_CHANGED`: ```json { "event_id": "019b21d9-c5d9-777d-80bd-d67c664bc6d9", "event": "ORDER_STATUS_CHANGED", "occurred_at": "2024-01-15T10:30:00Z", "data": { "order_id": "019b21d9-c5d9-777d-80bd-d67c664bc6d9", "new_status": "DELIVERED" } } Пример payload для `ORDER_PAYMENT_STATUS_CHANGED`: ```json { "event_id": "019b21d9-c5d9-777d-80bd-d67c664bc6d9", "event": "ORDER_PAYMENT_STATUS_CHANGED", "occurred_at": "2024-01-15T10:30:00Z", "data": { "order_id": "019b21d9-c5d9-777d-80bd-d67c664bc6d9", "new_payment_status": "PAYMENT_PAID" } } ``` Пример payload для `ORDER_DELIVERY_STATUS_CHANGED`: ```json { "event_id": "019b21d9-c5d9-777d-80bd-d67c664bc6d9", "event": "ORDER_DELIVERY_STATUS_CHANGED", "occurred_at": "2024-01-15T10:30:00Z", "data": { "order_id": "019b21d9-c5d9-777d-80bd-d67c664bc6d9", "chunk_id": 1, "new_delivery_status": "DELIVERED" } } ``` ## Верификация подписи Каждый запрос содержит заголовок `X-Webhook-Signature` — HMAC-SHA256 от тела запроса, вычисленный с помощью поля `secret` вебхука. Используйте его для проверки подлинности входящего запроса: {% cut "Запрос" %} ``` expected = HMAC-SHA256(key=secret, data=request_body) valid = (X-Webhook-Signature == hex(expected)) ``` {% endcut %} ## Повторные попытки доставки Система повторяет доставку с экспоненциальной задержкой при следующих кодах ответа сервера: - `5xx` — серверные ошибки. - `408 Request Timeout` — таймаут запроса. - `429 Too Many Requests` — слишком много запросов. | Попытка | Задержка перед попыткой | |---------|------------------------| | 1 | — | | 2 | 1 сек | | 3 | 4 сек | | 4 | 16 сек | | 5 | ~1 мин | | 6 | ~4 мин | | 7 | 10 мин | | 8 | 10 мин | {% cut "Параметры" %} * Начальный интервал — 1 сек. * Коэффициент — 4. * Максимальный интервал — 10 мин. * Максимум попыток — 8. * Общее окно — 10 мин. После исчерпания попыток событие считается недоставленным и больше не отправляется. {% endcut %} ## Порядок доставки Доставка вебхуков не гарантируется в хронологическом порядке: событие, которое произошло позже, может быть доставлено раньше. Чтобы восстановить правильную хронологию, используйте поле `occurred_at` из payload ## Активация вебхука После создания вебхук находится в статусе `INACTIVE` и не отправляет уведомления. Чтобы активировать вебхук: 1. Вызовите `POST /v1/webhooks/{webhook_id}/validate?activate=true`. 2. Система отправит POST-запрос на ваш URL с телом — `{"event_id": "...", "event": "WEBHOOK_VALIDATE", "occurred_at": "..."}`. 3. Ваш сервер должен вернуть HTTP 2xx с телом: ```json { "message": "validated_store_{store_id}" } ``` * `{store_id}` — идентификатор вашего магазина (доступен через `GET /v1/store`). 4. При успешной проверке вебхук автоматически изменит статус на `ACTIVE`. 5. При изменении URL вебхука он переходит в статус `INACTIVE`, после чего требуется повторная валидация. ## Endpoints - [Получение списка вебхуков](https://yandex.ru/dev/kit/ru/openapi/Vebhuki/GetWebhooks.md) - [Создание вебхука](https://yandex.ru/dev/kit/ru/openapi/Vebhuki/CreateWebhook.md) - [Валидация вебхука](https://yandex.ru/dev/kit/ru/openapi/Vebhuki/ValidateWebhook.md) - [Получение вебхука по уникальному идентификатору](https://yandex.ru/dev/kit/ru/openapi/Vebhuki/GetWebhookById.md) - [Удаление вебхука](https://yandex.ru/dev/kit/ru/openapi/Vebhuki/DeleteWebhook.md) - [Обновление вебхука](https://yandex.ru/dev/kit/ru/openapi/Vebhuki/UpdateWebhook.md)