Вебхуки
Управление вебхуками магазина.
Структура 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:
{
"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:
{
"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 вебхука.
Используйте его для проверки подлинности входящего запроса:
Запрос
expected = HMAC-SHA256(key=secret, data=request_body)
valid = (X-Webhook-Signature == hex(expected))
Повторные попытки доставки
Система повторяет доставку с экспоненциальной задержкой при следующих кодах ответа сервера:
5xx— серверные ошибки.408 Request Timeout— таймаут запроса.429 Too Many Requests— слишком много запросов.
| Попытка | Задержка перед попыткой |
|---|---|
| 1 | — |
| 2 | 1 сек |
| 3 | 4 сек |
| 4 | 16 сек |
| 5 | ~1 мин |
| 6 | ~4 мин |
| 7 | 10 мин |
| 8 | 10 мин |
Параметры
- Начальный интервал — 1 сек.
- Коэффициент — 4.
- Максимальный интервал — 10 мин.
- Максимум попыток — 8.
- Общее окно — 10 мин. После исчерпания попыток событие считается недоставленным и больше не отправляется.
Порядок доставки
Доставка вебхуков не гарантируется в хронологическом порядке: событие, которое произошло позже, может быть доставлено раньше.
Чтобы восстановить правильную хронологию, используйте поле occurred_at из payload
Активация вебхука
После создания вебхук находится в статусе INACTIVE и не отправляет уведомления.
Чтобы активировать вебхук:
- Вызовите
POST /v1/webhooks/{webhook_id}/validate?activate=true. - Система отправит POST-запрос на ваш URL с телом —
{"event_id": "...", "event": "WEBHOOK_VALIDATE", "occurred_at": "..."}. - Ваш сервер должен вернуть HTTP 2xx с телом:
{ "message": "validated_store_{store_id}" }{store_id}— идентификатор вашего магазина (доступен черезGET /v1/store).
- При успешной проверке вебхук автоматически изменит статус на
ACTIVE. - При изменении URL вебхука он переходит в статус
INACTIVE, после чего требуется повторная валидация.