Logo NinjabuyBusiness
Skontaktuj się z działem sprzedaży
API konta2026-11Podgląd

Endpointy webhooków

Adresy URL, pod które wysyłamy zdarzenia metodą POST. Zdarzenia, ich treść, podpisywanie i ponowienia są opisane w Webhookach.
Endpointy

Obiekt Webhook endpoint

idstring
Zaczyna się od we_.
urlstring
Twój adres URL https, który odpowiada 2xx.
descriptionstring|null
Dla ciebie.
events[]array
Typy zdarzeń do wysyłania albo * dla wszystkich, łącznie z typami dodanymi później: order.created, order.paid, order.bought, order.checked, order.shipped, product.cost_changed, product.out_of_stock, qc.issue.
statusstring
enabled lub disabled (przez ciebie albo przez nas po pięciu dniach, w których każde dostarczenie się nie udało; najpierw wysyłamy ci e-mail).
api_versionstring
Wersja, w której zapisywana jest treść zdarzeń; wersja klucza w chwili utworzenia.
secretstring
Sekret podpisu. Tylko w odpowiedziach na utworzenie i rotację.
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"
}

Utworzenie endpointu

POST/v1/webhook_endpoints

Zwraca sekret podpisu jeden raz: zapisz go od razu. Do 16 endpointów na konto.

Zakreswebhooks:write

Body

urlstringwymagane
Tylko https.
events[]arraywymagane
Typy zdarzeń lub ["*"].
descriptionstring
Opcjonalne.

Błędy

StatusTypKiedy
400bad-bodyURL nie jest https albo typ zdarzenia jest nieznany.
409invalid-stateKonto ma już 16 endpointów.
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"
}

Lista endpointów

GET/v1/webhook_endpoints

Każdy endpoint na koncie, bez sekretów.

Zakreswebhooks: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
}

Pobranie endpointu

GET/v1/webhook_endpoints/{id}

Jeden endpoint, bez sekretu.

Zakreswebhooks:write

Parametry ścieżki

idstringwymagane
ID endpointu.

Błędy

StatusTypKiedy
404not-foundNa tym koncie nie ma takiego endpointu.
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"
}

Aktualizacja endpointu

PATCH/v1/webhook_endpoints/{id}

Zmień jego URL lub zdarzenia albo go wyłącz i włącz. Włączenie wysyła to, co ominęło go w ostatnich 3 dniach.

Zakreswebhooks:write

Parametry ścieżki

idstringwymagane
ID endpointu.

Body

urlstring
Tylko https.
events[]array
Typy zdarzeń lub ["*"].
descriptionstring
Opcjonalne.
statusstring
Opcjonalne. enabled lub disabled.

Błędy

StatusTypKiedy
404not-foundNa tym koncie nie ma takiego endpointu.
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"
}

Usunięcie endpointu

DELETE/v1/webhook_endpoints/{id}

Od razu zatrzymuje każde dostarczenie do niego, w tym ponowienia.

Zakreswebhooks:write

Parametry ścieżki

idstringwymagane
ID endpointu.

Błędy

StatusTypKiedy
404not-foundNa tym koncie nie ma takiego endpointu.
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 }

Rotacja sekretu

POST/v1/webhook_endpoints/{id}/rotate_secret

Zwraca nowy sekret. Przez 24 godziny podpisujemy oboma, więc nagłówek webhook-signature zawiera dwa podpisy i weryfikuje dowolny z nich: wdróż nowy, potem pozwól staremu wygasnąć.

Zakreswebhooks:write

Parametry ścieżki

idstringwymagane
ID endpointu.

Błędy

StatusTypKiedy
404not-foundNa tym koncie nie ma takiego endpointu.
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"
}

Wysłanie zdarzenia testowego

POST/v1/webhook_endpoints/{id}/test

Wysyła przykład jednego typu zdarzenia, podpisany jak każde inne, z test: true. Zwraca, jak odpowiedział twój endpoint.

Zakreswebhooks:write

Parametry ścieżki

idstringwymagane
ID endpointu.

Body

typestringwymagane
Typ zdarzenia.

Błędy

StatusTypKiedy
404not-foundNa tym koncie nie ma takiego endpointu.
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
}

Lista dostarczeń

GET/v1/webhook_endpoints/{id}/deliveries

Każda próba z ostatnich 30 dni, od najnowszej: co wysłaliśmy, jak odpowiedziałeś i kiedy ponowimy.

Zakreswebhooks:write

Parametry ścieżki

idstringwymagane
ID endpointu.

Parametry zapytania

statusstring
Opcjonalne. succeeded, retrying lub failed.
eventstring
Opcjonalne. ID zdarzenia.
limit, cursor
Pagination

Błędy

StatusTypKiedy
404not-foundNa tym koncie nie ma takiego endpointu.
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
}

Ponowne wysłanie dostarczenia

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

Wysyła zdarzenie teraz, z tym samym webhook-id, niezależnie od jego stanu. Zaplanowane już ponowienia trwają dalej.

Zakreswebhooks:write

Parametry ścieżki

idstringwymagane
ID endpointu.
deliverystringwymagane
ID dostarczenia.

Błędy

StatusTypKiedy
404not-foundNa tym koncie nie ma takiego endpointu.
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"
}