Вебхуки продавца (webhooks_general)
Методы вебхуков продавца доступны для всех сервисов из Каталога решений для бизнеса
Методы вебхуков продавца доступны для всех сервисов из Каталога решений для бизнеса
Вебхуки позволяют получать уведомления о событиях на аккаунте продавца в реальном времени. Вебхуки отправляются автоматически, поэтому, чтобы узнавать о новых событиях, нет необходимости постоянно использовать API.
Создание вебхуков через API доступно для всех сервисов из Каталога решений для бизнеса. Каждый сервис может управлять только своими вебхуками и не имеет доступа к вебхукам продавца, созданным другими сервисами. Если продавец отключает сервис, созданные вебхуки также отключаются, и события на них перестают отправляться.
Можно создать несколько вебхуков. На каждый можно получать один или несколько типов событий. Уведомления о событиях в виде HTTP-запроса будут сразу отправляться на URL-адрес, указанный при создании вебхука.
Один запрос может содержать несколько событий, если:
- события происходят одновременно.
- доставка события была отложена из-за недоступности URL, указанного при создании вебхука.
Доступ к API вебхуков возможен с JWT-токеном любых категорий. Для подписки вебхука на событие токен должен содержать скоуп этого события. То есть, если вы хотите создать вебхук для событий завершения генерации отчёта, вы можете сделать это только с токеном категории Аналитика.
Чтобы убедиться, что уведомления о событии поступают от WB, нужно проверять заголовок Authorization в запросах. В Authorization передаётся секрет, сгенерированный при создании вебхука.
В ответ на HTTP-запрос с событиями ваш сервис должен вернуть статус доставки 200 в течение 10 секунд. В противном случае доставка будет считаться неуспешной. Попытки доставки будут повторяться с нарастающим интервалом от 10 секунд до 15 минут, после чего событие будет удалено. Если вебхук не принимает события в течение длительного времени, он может быть отключён.
В правой колонке указаны методы, которые генерируют данный тип событий.
| Событие | Категория | Описание | Методы |
|---|---|---|---|
| report_generation_complete | contentanalytics | Генерация отчёта завершена | • Создать отчёт об остатках на складах • Создать отчёт о платной приёмке • Создать отчёт о платном хранении |
| card_creation_error | content | Ошибка создания карточки товара | Создание карточек товаров |
| card_changed | content | Карточка товара изменена. Без списка ярлыков и URL фото и видео |
• Редактирование карточек товаров • Удаление карточки товара (не API) |
| feedback_updated | questionsandfeedback | Создан или изменён отзыв | • Создание и редактирование отзывов покупателями • Работа с отзывами |
Список событий будет расширен.
В редких случаях из-за проблем со связью уведомления могут приходить повторно. Чтобы гарантировать обработку событий только один раз, можно использовать ключ идемпотентности idempotencyKey, который указывается для каждого события.
Чтобы протестировать интеграцию с сервисом вебхуков, можно генерировать тестовые события. Тестовые события содержат поле "test": true.
Получить типы событий{{ /api/v1/event-scopes }}
Метод предоставляет информацию о категориях и типах событий, которые можно получить через вебхуки.
В правой колонке указаны методы, которые генерируют данный тип событий.
| Событие | Категория | Описание | Методы |
|---|---|---|---|
| report_generation_complete | contentanalytics | Генерация отчёта завершена | • Создать отчёт об остатках на складах • Создать отчёт о платной приёмке • Создать отчёт о платном хранении |
| card_creation_error | content | Ошибка создания карточки товара | Создание карточек товаров |
| card_changed | content | Карточка товара изменена. Без списка ярлыков и URL фото и видео |
• Редактирование карточек товаров • Удаление карточки товара (не API) |
| feedback_updated | questionsandfeedback | Создан или изменён отзыв | • Создание и редактирование отзывов покупателями • Работа с отзывами |
Authorizations:
Responses
Response samples
- 200
- 401
- 403
- 429
{- "eventScopes": [
- {
- "name": "Content",
- "key": "content",
- "eventTypes": [
- {
- "name": "card_creation_error",
- "key": "card_creation_error"
}
]
}
]
}Создать вебхук{{ /api/v1/webhooks }}
Метод создаёт новый вебхук. Также метод возвращает секрет, который позже нельзя будет получить через другие методы. Секрет можно только сгенерировать заново.
После создания нельзя изменить URL, на который будут приходить вебхуки.
Authorizations:
Request Body schema: application/jsonrequired
| enabled required | boolean Включён ли вебхук для приёма событий |
| url required | string <uri> (WebhookUrl) [ 10 .. 200 ] characters Адрес вебхука |
| name required | string (WebhookName) [ 3 .. 60 ] characters Название вебхука |
required | Array of objects (EventTypesByScope) unique Типы событий, на которые подписан вебхук |
Responses
Request samples
- Payload
{- "enabled": false,
- "name": "Мой вебхук",
- "subscriptions": [
- {
- "scope": "contentanalytics",
- "event": "report_generation_complete"
}
]
}Response samples
- 200
- 400
- 401
- 403
- 429
{- "id": "0192be68-68ea-778b-920d-51ec98f99468",
- "enabled": true,
- "name": "Мой вебхук для всего",
- "createdAt": "2024-12-12T03:58:41.554Z",
- "updatedAt": "2024-12-12T03:58:41.554Z",
- "subscriptions": [
- {
- "scope": "contentanalytics",
- "event": "report_generation_complete"
}
], - "secret": "very-secret"
}Получить вебхуки{{ /api/v1/webhooks }}
Метод предоставляет информацию обо всех вебхуках продавца.
В ответе не будет указан секрет, его можно получить только при создании вебхука или сгенерировать новый секрет.
Authorizations:
query Parameters
| order | string Enum: "nameAsc" "nameDesc" "createdAtAsc" "createdAtDesc" "updatedAtAsc" "updatedAtDesc" Example: order=nameAsc Порядок данных в ответе |
Responses
Response samples
- 200
- 400
- 401
- 403
- 429
{- "webhooks": [
- {
- "id": "0192be68-68ea-778b-920d-51ec98f99468",
- "enabled": true,
- "name": "Мой вебхук для всего",
- "createdAt": "2024-12-12T03:58:41.554Z",
- "updatedAt": "2024-12-12T03:58:41.554Z",
- "subscriptions": [
- {
- "scope": "contentanalytics",
- "event": "report_generation_complete"
}
]
}
], - "total": 0,
- "limit": 0
}Получить вебхук{{ /api/v1/webhooks/{id} }}
Метод предоставляет данные одного вебхука из списка.
В ответе не будет указан секрет, его можно получить только при создании вебхука или сгенерировать новый секрет.
Authorizations:
path Parameters
| id required | string <UUID> Example: 5f18230f-aa81-4835-99ec-859613efd5bb ID вебхука |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
{- "id": "0192be68-68ea-778b-920d-51ec98f99468",
- "enabled": true,
- "name": "Мой вебхук для всего",
- "createdAt": "2024-12-12T03:58:41.554Z",
- "updatedAt": "2024-12-12T03:58:41.554Z",
- "subscriptions": [
- {
- "scope": "contentanalytics",
- "event": "report_generation_complete"
}
]
}Редактировать вебхук{{ /api/v1/webhooks/{id} }}
Метод редактирует основные данные вебхука.
При этом изменить URL, на который будут приходить вебхуки, нельзя. Вместо этого вы можете создать новый вебхук.
Authorizations:
path Parameters
| id required | string <UUID> Example: 01932967-96d4-76f3-9e49-8e1bbc54624f ID вебхука |
Request Body schema: application/jsonrequired
| enabled required | boolean Включён ли вебхук для приёма событий |
| name required | string [ 3 .. 60 ] characters Название вебхука |
required | Array of objects (EventTypesByScope) unique Типы событий, на которые подписан вебхук |
Responses
Request samples
- Payload
{- "enabled": true,
- "name": "My Webhook",
- "subscriptions": [
- {
- "scope": "contentanalytics",
- "event": "report_generation_complete"
}
]
}Response samples
- 200
- 400
- 401
- 403
- 404
- 429
{- "id": "0192be68-68ea-778b-920d-51ec98f99468",
- "enabled": true,
- "name": "Мой вебхук для всего",
- "createdAt": "2024-12-12T03:58:41.554Z",
- "updatedAt": "2024-12-12T03:58:41.554Z",
- "subscriptions": [
- {
- "scope": "contentanalytics",
- "event": "report_generation_complete"
}
]
}Удалить вебхук{{ /api/v1/webhooks/{id} }}
Метод удаляет вебхук. После удаления отправка событий по этому вебхуку прекращается.
Authorizations:
path Parameters
| id required | string <UUID> Example: 01932967-96d4-76f3-9e49-8e1bbc54624f ID вебхука |
Responses
Response samples
- 400
- 401
- 403
- 404
- 429
{- "title": "string",
- "detail": "string",
- "requestId": "string",
- "origin": "string",
- "errors": [
- {
- "message": "string",
- "location": "string",
- "value": null
}
]
}Проверить доступ URL{{ /api/v1/webhooks/check }}
Метод проверяет, доступен ли URL, который будет указан для создания вебхука.
Authorizations:
Request Body schema: application/jsonrequired
| url required | string URL-адрес вебхука для проверки |
Responses
Request samples
- Payload
{
}Response samples
- 200
- 400
- 401
- 403
- 429
{- "success": true,
- "error": "Timeout exceeded",
- "checkStatus": 200
}Обновить секрет вебхука{{ /api/v1/webhooks/{id}/secret/refresh }}
Метод заново генерирует секрет для отправки вебхуков.
Секрет можно получить только при создании вебхука, в методе получения вебхуков он не возвращается. Поэтому, если вы потеряли секрет, рекомендуем использовать этот метод.
Authorizations:
path Parameters
| id required | string <UUID> Example: 327fe358-e79e-435a-afe2-db7c9dfab448 ID вебхука |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
{- "secret": "r8WS-PYrF0Rb8JwNBx4Du1Fg5qSfmqsQxL4lUmfP-FI"
}Отправить тестовое событие{{ /api/v1/webhooks/{id}/test/send }}
Метод генерирует тестовые события для отправки на вебхук. У данных событий в поле "test" будет указано true.
Если URL не подписан ни на какие события, метод возвращает статус-код 409.
Authorizations:
path Parameters
| id required | string <UUID> Example: 01932967-96d4-76f3-9e49-8e1bbc54624f ID вебхука |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 409
- 429
{- "events": [
- {
- "id": "01934393-1283-7599-88a0-9b649447b7c9",
- "scope": "content",
- "type": "card_creation_error"
}
]
}Каждое событие и каждая попытка доставки события попадает в историю или логи доставки. Вы можете получить логи с помощью этих методов. Событие попадает в историю, если хотя бы один вебхук продавца подписан на это событие. У каждого события может быть одна или несколько попыток доставки, если вебхук отвечал ошибками или был недоступен.
Каждая доставка может содержать одно или несколько событий. В истории операций можно посмотреть, кто и когда создавал и редактировал вебхуки.
Список событий{{ /api/v1/events }}
Метод предоставляет все события продавца, если на них подписан хотя бы один вебхук.
Authorizations:
query Parameters
| webhookId | string <UUID> Example: webhookId=019520ca-a739-7305-b438-77ca7e876cd1 Фильтр по вебхуку |
| limit | integer [ 1 .. 1000 ] Default: 100 Example: limit=100 Количество записей в ответе |
| next | string Example: next=e7bfb68a-917f-4b7e-b113-1dfe2e5c7a90 Курсор для получения следующего блока данных |
| prev | string Example: prev=3e9fda19-bc90-4207-8881-3d15d17c86dc Курсор для получения предыдущего блока данных |
| from | string <RFC3339> Example: from=2020-11-23T13:48:56Z Начало интервала времени для получения данных |
| to | string <RFC3339> Example: to=2022-11-23T13:48:56Z Конец интервала времени для получения данных |
Responses
Response samples
- 200
- 400
- 401
- 403
- 429
{- "events": [
- {
- "id": "01951e00-d818-74bf-b0c0-b41479c0826e",
- "idempotencyKey": "2f8c7ffd86ecebc828335d2ab4d643b971adb24101fccdd763919b73",
- "time": "2025-02-21T00:35:26.389710263Z",
- "type": "report_generation_complete",
- "scope": "content",
- "test": false,
- "payload": [
- {
- "vendorCode": "vendor-code",
- "updateAt": "2025-02-19T07:59:27Z",
- "subjectID": 0,
- "translations": {
- "en": {
- "subject": "subject-en",
- "errors": [
- "error-en"
]
}, - "ru": {
- "subject": "subject-ru",
- "errors": [
- "error-ru"
]
}
}
}
]
}
], - "next": "01951d38-2b6b-765b-8ed9-6cc31da5df50",
- "prev": "01951d38-2891-7864-ba6e-6006f248e793"
}Событие{{ /api/v1/events/{event-id} }}
Метод предоставляет данные одного события из списка.
Authorizations:
path Parameters
| event-id required | string <UUID> Example: 019520ca-a739-7305-b438-77ca7e876cd1 ID события |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
{- "id": "01951e00-d818-74bf-b0c0-b41479c0826e",
- "idempotencyKey": "2f8c7ffd86ecebc828335d2ab4d643b971adb24101fccdd763919b73",
- "time": "2025-02-21T00:35:26.389710263Z",
- "type": "report_generation_complete",
- "scope": "content",
- "test": false,
- "payload": [
- {
- "vendorCode": "vendor-code",
- "updateAt": "2025-02-19T07:59:27Z",
- "subjectID": 0,
- "translations": {
- "en": {
- "subject": "subject-en",
- "errors": [
- "error-en"
]
}, - "ru": {
- "subject": "subject-ru",
- "errors": [
- "error-ru"
]
}
}
}
]
}Доставки одного события{{ /api/v1/events/{event-id}/deliveries }}
Метод предоставляет данные доставок одного события из списка.
Если на событие подписано несколько вебхуков, данные возвращаются по всем вебхукам.
Authorizations:
path Parameters
| event-id required | string <UUID> Example: 019520ca-a739-7305-b438-77ca7e876cd1 ID события |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
{- "deliveries": [
- {
- "id": "01951e53-f958-7ab8-be23-af75f392b869",
- "time": "2025-02-19T13:09:29Z",
- "webhookId": "0195179e-9fed-7658-9874-d36b1ba0ef7f",
- "success": false,
- "responseCode": 200,
- "error": "Timeout exceeded"
}
]
}Доставки всех событий{{ /api/v1/deliveries }}
Метод предоставляет данные доставок всех событий.
Authorizations:
query Parameters
| webhookId | string <UUID> Example: webhookId=019520ca-a739-7305-b438-77ca7e876cd1 Фильтр по вебхуку |
| limit | integer [ 1 .. 1000 ] Default: 100 Example: limit=100 Количество записей в ответе |
| next | string Example: next=e7bfb68a-917f-4b7e-b113-1dfe2e5c7a90 Курсор для получения следующего блока данных |
| prev | string Example: prev=3e9fda19-bc90-4207-8881-3d15d17c86dc Курсор для получения предыдущего блока данных |
| from | string <RFC3339> Example: from=2020-11-23T13:48:56Z Начало интервала времени для получения данных |
| to | string <RFC3339> Example: to=2022-11-23T13:48:56Z Конец интервала времени для получения данных |
Responses
Response samples
- 200
- 400
- 401
- 403
- 429
{- "deliveries": [
- {
- "id": "01951e53-f958-7ab8-be23-af75f392b869",
- "time": "2025-02-19T13:09:29Z",
- "webhookId": "0195179e-9fed-7658-9874-d36b1ba0ef7f",
- "success": false,
- "responseCode": 200,
- "error": "Timeout exceeded"
}
], - "next": "string",
- "prev": "string"
}Одна доставка события{{ /api/v1/deliveries/{delivery-id} }}
Метод предоставляет данные одной доставки из списка.
Authorizations:
path Parameters
| delivery-id required | string <UUID> Example: 019520ca-a739-7305-b438-77ca7e876cd1 ID доставки |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
{- "id": "01951e53-f958-7ab8-be23-af75f392b869",
- "time": "2025-02-19T13:09:29Z",
- "webhookId": "0195179e-9fed-7658-9874-d36b1ba0ef7f",
- "success": false,
- "responseCode": 200,
- "error": "Timeout exceeded"
}История изменений вебхука{{ /api/v1/history }}
Метод предоставляет историю изменений всех вебхуков.
Authorizations:
query Parameters
| limit | integer [ 1 .. 1000 ] Default: 100 Example: limit=100 Количество записей в ответе |
| next | string Example: next=e7bfb68a-917f-4b7e-b113-1dfe2e5c7a90 Курсор для получения следующего блока данных |
| prev | string Example: prev=3e9fda19-bc90-4207-8881-3d15d17c86dc Курсор для получения предыдущего блока данных |
| from | string <RFC3339> Example: from=2020-11-23T13:48:56Z Начало интервала времени для получения данных |
| to | string <RFC3339> Example: to=2022-11-23T13:48:56Z Конец интервала времени для получения данных |
Responses
Response samples
- 200
- 400
- 401
- 403
- 429
{- "history": [
- {
- "id": "019528d4-0ea5-7a75-a19d-d942847cf9b9",
- "time": "2025-02-21T14:05:40Z",
- "ip": "192.168.1.1",
- "userId": 111222,
- "source": "api",
- "action": "UpdateWebhook",
- "request": {
- "webhookId": "019528d2-d539-7b27-8483-d01c8d27c855"
}, - "response": {
- "webhookId": "019528d2-d539-7b27-8483-d01c8d27c855"
}, - "error": "validation error"
}
], - "next": "string",
- "prev": "string"
}Детали изменения{{ /api/v1/history/{history-id} }}
Метод предоставляет данные одного изменения вебхука из списка изменений.
Authorizations:
path Parameters
| history-id required | string <UUID> Example: 019520ca-a739-7305-b438-77ca7e876cd1 ID операции |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
{- "id": "019528d4-0ea5-7a75-a19d-d942847cf9b9",
- "time": "2025-02-21T14:05:40Z",
- "ip": "192.168.1.1",
- "userId": 111222,
- "source": "api",
- "action": "UpdateWebhook",
- "request": {
- "webhookId": "019528d2-d539-7b27-8483-d01c8d27c855"
}, - "response": {
- "webhookId": "019528d2-d539-7b27-8483-d01c8d27c855"
}, - "error": "validation error"
}В данном разделе вы можете увидеть, в каком формате вам будут приходить события по вебхукам. События отправляются на URL вебхука в виде POST запроса.
Для приема событий вебхуков рекомендуем проверять:
- Секрет вебхука
- Поле
test— является ли вебхук тестовым.
Уведомления о событиях Webhook
header Parameters
| Authorization required | string Example: NIFirgRN1oLDb2NkIkd06yHzo4dcRn9ptnD04RXH8ZY Секретный ключ вебхука |
Request Body schema: application/json
| sellerId | string <UUID> ID продавца |
| requestId | string <UUID> ID запроса |
Array of any |
Request samples
- Payload
Ошибка создания карточки товара
{- "sellerId": "f0870d53-f9a2-4965-9655-db642c08d509",
- "requestId": "2a9092fa-8c83-490b-96aa-a18afe3b02c8",
- "events": [
- {
- "id": "01951462-4e43-7bee-a121-1fe1db0e5272",
- "idempotencyKey": "23fee5e9380d4acab66e45cd645443fd4357ea6e1b92a825e1bb7b15",
- "time": "2025-02-17T14:49:00.013Z",
- "scope": "content",
- "type": "card_creation_error",
- "test": false,
- "payload": {
- "vendorCode": "АртикулПродавца",
- "updateAt": "2025-02-17T14:48:55Z",
- "subjectID": 105,
- "translations": {
- "en": {
- "subject": "Trainers shoes",
- "errors": [
- "Inadmissible color value \"red\"",
- "Non -unique barcode: a product with barcode 88005553535 you already have: 211807640. Please change the barcode, it should not be repeated."
]
}, - "ru": {
- "subject": "Кроссовки",
- "errors": [
- "Недопустимое значение цвета \"red\"",
- "Неуникальный баркод: товар с баркодом 88005553535 уже есть у вас: 211807640. Пожалуйста, измените баркод, он не должен повторяться."
]
}, - "zh": {
- "subject": "运动鞋",
- "errors": [
- "不可接受的颜色值“ red”",
- "非唯一条形码：带条形码88005553535的产品您已经有：211807640。请更改条形码，不应重复。"
]
}
}
}
}
]
}