Konto-API2026-11Vorschau

Webhook-Endpunkte

Die URLs, an die wir Events per POST senden. Die Events, ihre Payloads, Signierung und Wiederholungen stehen unter Webhooks.

Endpunkte

POST/v1/webhook_endpointsEndpunkt anlegen
GET/v1/webhook_endpointsEndpunkte auflisten
GET/v1/webhook_endpoints/{id}Einen Endpunkt abrufen
PATCH/v1/webhook_endpoints/{id}Einen Endpunkt aktualisieren
DELETE/v1/webhook_endpoints/{id}Einen Endpunkt löschen
POST/v1/webhook_endpoints/{id}/rotate_secretDas Secret rotieren
POST/v1/webhook_endpoints/{id}/testEin Test-Event senden
GET/v1/webhook_endpoints/{id}/deliveriesZustellungen auflisten
POST/v1/webhook_endpoints/{id}/deliveries/{delivery}/retryEine Zustellung erneut senden

Das Webhook-Endpoint-Objekt

idstring: Beginnt mit we_.
urlstring: Eine https-URL von dir, die mit 2xx antwortet.
descriptionstring|null: Für dich.
events[]array: Die zu sendenden Event-Typen oder * für alle, einschließlich später hinzugefügter Typen: order.created, order.paid, order.bought, order.checked, order.shipped, product.cost_changed, product.out_of_stock, qc.issue.
statusstring: enabled oder disabled (von dir oder von uns nach fünf Tagen, in denen jede Zustellung fehlgeschlagen ist; wir schicken dir vorher eine E-Mail).
api_versionstring: Die Version, in der Event-Payloads geschrieben sind; die des Schlüssels beim Anlegen.
secretstring: Das Signatur-Secret. Nur in den Antworten auf Anlegen und Rotieren.

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"
}

Endpunkt anlegen

POST/v1/webhook_endpoints

Antwortet einmalig mit dem Signatur-Secret: Speichere es jetzt. Bis zu 16 Endpunkte pro Konto.

Scopewebhooks:write

Body

urlstringerforderlich: Nur https.
events[]arrayerforderlich: Event-Typen oder ["*"].
descriptionstring: Optional.

Fehler

Status	Typ	Wann
400	bad-body	Die URL ist nicht https, oder ein Event-Typ ist unbekannt.
409	invalid-state	Das Konto hat schon 16 Endpunkte.

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"
}

Endpunkte auflisten

GET/v1/webhook_endpoints

Jeder Endpunkt des Kontos, ohne Secrets.

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

Einen Endpunkt abrufen

GET/v1/webhook_endpoints/{id}

Ein Endpunkt, ohne sein Secret.

Scopewebhooks:write

Pfadparameter

idstringerforderlich: Die ID des Endpunkts.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Endpunkt in diesem Konto.

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"
}

Einen Endpunkt aktualisieren

PATCH/v1/webhook_endpoints/{id}

Ändere seine URL oder Events oder deaktiviere und aktiviere ihn. Das Aktivieren sendet, was er in den letzten 3 Tagen verpasst hat.

Scopewebhooks:write

Pfadparameter

idstringerforderlich: Die ID des Endpunkts.

Body

urlstring: Nur https.
events[]array: Event-Typen oder ["*"].
descriptionstring: Optional.
statusstring: Optional. enabled oder disabled.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Endpunkt in diesem Konto.

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"
}

Einen Endpunkt löschen

DELETE/v1/webhook_endpoints/{id}

Stoppt sofort jede Zustellung daran, Wiederholungen eingeschlossen.

Scopewebhooks:write

Pfadparameter

idstringerforderlich: Die ID des Endpunkts.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Endpunkt in diesem Konto.

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 }

Das Secret rotieren

POST/v1/webhook_endpoints/{id}/rotate_secret

Antwortet mit einem neuen Secret. 24 Stunden lang signieren wir mit beiden, der webhook-signature-Header trägt also zwei Signaturen und jede verifiziert: Setz das neue ein, dann lass das alte auslaufen.

Scopewebhooks:write

Pfadparameter

idstringerforderlich: Die ID des Endpunkts.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Endpunkt in diesem Konto.

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"
}

Ein Test-Event senden

POST/v1/webhook_endpoints/{id}/test

Sendet ein Beispiel eines Event-Typs, signiert wie jedes andere, mit test: true. Antwortet mit dem, was dein Endpunkt geantwortet hat.

Scopewebhooks:write

Pfadparameter

idstringerforderlich: Die ID des Endpunkts.

Body

typestringerforderlich: Ein Event-Typ.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Endpunkt in diesem Konto.

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
}

Zustellungen auflisten

GET/v1/webhook_endpoints/{id}/deliveries

Jeder Versuch der letzten 30 Tage, neueste zuerst: was wir gesendet haben, wie du geantwortet hast und wann wir es erneut versuchen.

Scopewebhooks:write

Pfadparameter

idstringerforderlich: Die ID des Endpunkts.

Query-Parameter

statusstring: Optional. succeeded, retrying oder failed.
eventstring: Optional. Eine Event-ID.
limit, cursor: Pagination

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Endpunkt in diesem Konto.

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
}

Eine Zustellung erneut senden

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

Sendet das Event jetzt, mit derselben webhook-id, egal in welchem Zustand. Bereits geplante Wiederholungen laufen weiter.

Scopewebhooks:write

Pfadparameter

idstringerforderlich: Die ID des Endpunkts.
deliverystringerforderlich: Eine Zustellungs-ID.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Endpunkt in diesem Konto.

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"
}