Логотип NinjabuyBusiness
Связаться с отделом продаж
API аккаунта2026-11Предпросмотр

Эндпоинты вебхуков

URL, на которые мы отправляем события методом POST. События, их содержимое, подпись и повторы описаны в разделе Вебхуки.
Эндпоинты

Объект Webhook endpoint

idstring
Начинается с we_.
urlstring
Ваш https URL, отвечающий 2xx.
descriptionstring|null
Для вас.
events[]array
Типы событий для отправки или * для всех, включая добавленные позже: order.created, order.paid, order.bought, order.checked, order.shipped, product.cost_changed, product.out_of_stock, qc.issue.
statusstring
enabled или disabled (вами либо нами после пяти дней, в которые все доставки не удались; сначала мы пишем вам).
api_versionstring
Версия, в которой записано содержимое событий; версия ключа на момент создания.
secretstring
Секрет подписи. Только в ответах на создание и ротацию.
webhook_endpoint
{
  "id": "we_3d8s",
  "url": "https://acme-goods.com/hooks/ninjabuy",
  "description": "Order sync",
  "events": ["order.shipped", "product.out_of_stock", "qc.issue"],
  "status": "enabled",
  "api_version": "2026-11",
  "created_at": "2026-11-01T08:00:00Z"
}

Создание эндпоинта

POST/v1/webhook_endpoints

Возвращает секрет подписи один раз: сохраните его сразу. До 16 эндпоинтов на аккаунт.

Область доступаwebhooks:write

Тело

urlstringобязательно
Только https.
events[]arrayобязательно
Типы событий или ["*"].
descriptionstring
Необязательно.

Ошибки

СтатусТипКогда
400bad-bodyURL не https, или тип события неизвестен.
409invalid-stateУ аккаунта уже 16 эндпоинтов.
curl -X POST "https://www.ninjabuy.com/api/v1/webhook_endpoints" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme-goods.com/hooks/ninjabuy",
    "events": ["order.shipped", "product.out_of_stock", "qc.issue"],
    "description": "Order sync"
  }'
Response 201
HTTP/2 201 Created

{
  "id": "we_3d8s",
  "url": "https://acme-goods.com/hooks/ninjabuy",
  "description": "Order sync",
  "events": ["order.shipped", "product.out_of_stock", "qc.issue"],
  "status": "enabled",
  "api_version": "2026-11",
  "created_at": "2026-11-01T08:00:00Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}

Список эндпоинтов

GET/v1/webhook_endpoints

Все эндпоинты аккаунта, без секретов.

Область доступаwebhooks:write

curl "https://www.ninjabuy.com/api/v1/webhook_endpoints" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "data": [
    {
      "id": "we_3d8s",
      "url": "https://acme-goods.com/hooks/ninjabuy",
      "description": "Order sync",
      "events": ["order.shipped", "product.out_of_stock", "qc.issue"],
      "status": "enabled",
      "api_version": "2026-11",
      "created_at": "2026-11-01T08:00:00Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

Получение эндпоинта

GET/v1/webhook_endpoints/{id}

Один эндпоинт, без секрета.

Область доступаwebhooks:write

Параметры пути

idstringобязательно
ID эндпоинта.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого эндпоинта.
curl "https://www.ninjabuy.com/api/v1/webhook_endpoints/we_3d8s" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "id": "we_3d8s",
  "url": "https://acme-goods.com/hooks/ninjabuy",
  "description": "Order sync",
  "events": ["order.shipped", "product.out_of_stock", "qc.issue"],
  "status": "enabled",
  "api_version": "2026-11",
  "created_at": "2026-11-01T08:00:00Z"
}

Изменение эндпоинта

PATCH/v1/webhook_endpoints/{id}

Измените URL или события, отключите или включите его. При включении отправляется то, что он пропустил за последние 3 дня.

Область доступаwebhooks:write

Параметры пути

idstringобязательно
ID эндпоинта.

Тело

urlstring
Только https.
events[]array
Типы событий или ["*"].
descriptionstring
Необязательно.
statusstring
Необязательно. enabled или disabled.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого эндпоинта.
curl -X PATCH "https://www.ninjabuy.com/api/v1/webhook_endpoints/we_3d8s" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["*"] }'
Response 200
HTTP/2 200 OK

{
  "id": "we_3d8s",
  "url": "https://acme-goods.com/hooks/ninjabuy",
  "description": "Order sync",
  "events": ["*"],
  "status": "enabled",
  "api_version": "2026-11",
  "created_at": "2026-11-01T08:00:00Z"
}

Удаление эндпоинта

DELETE/v1/webhook_endpoints/{id}

Сразу останавливает все доставки на него, включая повторы.

Область доступаwebhooks:write

Параметры пути

idstringобязательно
ID эндпоинта.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого эндпоинта.
curl -X DELETE "https://www.ninjabuy.com/api/v1/webhook_endpoints/we_3d8s" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{ "id": "we_3d8s", "deleted": true }

Ротация секрета

POST/v1/webhook_endpoints/{id}/rotate_secret

Возвращает новый секрет. 24 часа мы подписываем обоими, поэтому заголовок webhook-signature содержит две подписи и подходит любая: разверните новый секрет, а старый пусть истечёт.

Область доступаwebhooks:write

Параметры пути

idstringобязательно
ID эндпоинта.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого эндпоинта.
curl -X POST "https://www.ninjabuy.com/api/v1/webhook_endpoints/we_3d8s/rotate_secret" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"
Response 200
HTTP/2 200 OK

{
  "id": "we_3d8s",
  "secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD",
  "previous_expires_at": "2026-11-05T09:30:00Z"
}

Отправка тестового события

POST/v1/webhook_endpoints/{id}/test

Отправляет пример одного типа события, подписанный как обычно, с test: true. Возвращает, как ответил ваш эндпоинт.

Область доступаwebhooks:write

Параметры пути

idstringобязательно
ID эндпоинта.

Тело

typestringобязательно
Тип события.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого эндпоинта.
curl -X POST "https://www.ninjabuy.com/api/v1/webhook_endpoints/we_3d8s/test" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "type": "qc.issue" }'
Response 200
HTTP/2 200 OK

{
  "delivery": "dlv_0k2p",
  "event": "evt_test_6c3h",
  "response_status": 200,
  "duration_ms": 182
}

Список доставок

GET/v1/webhook_endpoints/{id}/deliveries

Все попытки за последние 30 дней, от новых к старым: что мы отправили, как вы ответили и когда мы повторим.

Область доступаwebhooks:write

Параметры пути

idstringобязательно
ID эндпоинта.

Параметры запроса

statusstring
Необязательно. succeeded, retrying или failed.
eventstring
Необязательно. ID события.
limit, cursor
Pagination

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого эндпоинта.
curl "https://www.ninjabuy.com/api/v1/webhook_endpoints/we_3d8s/deliveries?status=retrying" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "data": [
    {
      "id": "dlv_0k3a",
      "event": "evt_4m2x",
      "type": "order.shipped",
      "status": "retrying",
      "attempts": 3,
      "last_response_status": 502,
      "next_attempt_at": "2026-11-03T08:35:00Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

Повторная отправка доставки

POST/v1/webhook_endpoints/{id}/deliveries/{delivery}/retry

Отправляет событие сейчас, с тем же webhook-id, в каком бы состоянии оно ни было. Уже запланированные повторы продолжаются.

Область доступаwebhooks:write

Параметры пути

idstringобязательно
ID эндпоинта.
deliverystringобязательно
ID доставки.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого эндпоинта.
curl -X POST "https://www.ninjabuy.com/api/v1/webhook_endpoints/we_3d8s/deliveries/dlv_0k3a/retry" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"
Response 202
HTTP/2 202 Accepted

{
  "delivery": "dlv_0k3a",
  "status": "retrying",
  "next_attempt_at": "2026-11-03T08:01:10Z"
}