Ninjabuy-logoBusiness
Contact met sales
Account-API2026-11Preview

Webhook-endpoints

De URL's waar we events naartoe POST'en. De events, hun payloads, ondertekening en herhalingen staan bij Webhooks.
Endpoints

Het Webhook endpoint-object

idstring
Begint met we_.
urlstring
Een https-URL van jou die 2xx antwoordt.
descriptionstring|null
Voor jou.
events[]array
De eventtypes om te sturen, of * voor alle, inclusief types die later worden toegevoegd: order.created, order.paid, order.bought, order.checked, order.shipped, product.cost_changed, product.out_of_stock, qc.issue.
statusstring
enabled, of disabled (door jou, of door ons na vijf dagen waarin elke aflevering mislukte; we mailen je eerst).
api_versionstring
De versie waarin eventpayloads worden geschreven; die van de sleutel bij het aanmaken.
secretstring
Het ondertekeningssecret. Alleen in de antwoorden op aanmaken en roteren.
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"
}

Een endpoint aanmaken

POST/v1/webhook_endpoints

Antwoordt één keer met het ondertekeningssecret: bewaar het nu. Tot 16 endpoints per account.

Scopewebhooks:write

Body

urlstringverplicht
Alleen https.
events[]arrayverplicht
Eventtypes, of ["*"].
descriptionstring
Optioneel.

Fouten

StatusTypeWanneer
400bad-bodyDe URL is geen https, of een eventtype is onbekend.
409invalid-stateHet account heeft al 16 endpoints.
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"
}

Endpoints opvragen

GET/v1/webhook_endpoints

Elk endpoint van het account, zonder 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
}

Een endpoint ophalen

GET/v1/webhook_endpoints/{id}

Eén endpoint, zonder secret.

Scopewebhooks:write

Padparameters

idstringverplicht
De id van het endpoint.

Fouten

StatusTypeWanneer
404not-foundDit endpoint bestaat niet op dit account.
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"
}

Een endpoint bijwerken

PATCH/v1/webhook_endpoints/{id}

Wijzig de URL of events, of schakel hem uit en weer in. Inschakelen stuurt wat hij de afgelopen 3 dagen heeft gemist.

Scopewebhooks:write

Padparameters

idstringverplicht
De id van het endpoint.

Body

urlstring
Alleen https.
events[]array
Eventtypes, of ["*"].
descriptionstring
Optioneel.
statusstring
Optioneel. enabled of disabled.

Fouten

StatusTypeWanneer
404not-foundDit endpoint bestaat niet op dit account.
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"
}

Een endpoint verwijderen

DELETE/v1/webhook_endpoints/{id}

Stopt meteen elke aflevering ernaartoe, herhalingen inbegrepen.

Scopewebhooks:write

Padparameters

idstringverplicht
De id van het endpoint.

Fouten

StatusTypeWanneer
404not-foundDit endpoint bestaat niet op dit account.
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 }

Het secret roteren

POST/v1/webhook_endpoints/{id}/rotate_secret

Antwoordt met een nieuw secret. 24 uur lang ondertekenen we met beide, dus de webhook-signature-header bevat twee handtekeningen en elk van beide verifieert: zet het nieuwe in gebruik en laat het oude verlopen.

Scopewebhooks:write

Padparameters

idstringverplicht
De id van het endpoint.

Fouten

StatusTypeWanneer
404not-foundDit endpoint bestaat niet op dit account.
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"
}

Een testevent sturen

POST/v1/webhook_endpoints/{id}/test

Stuurt een voorbeeld van één eventtype, ondertekend zoals elk ander, met test: true. Antwoordt met hoe je endpoint reageerde.

Scopewebhooks:write

Padparameters

idstringverplicht
De id van het endpoint.

Body

typestringverplicht
Een eventtype.

Fouten

StatusTypeWanneer
404not-foundDit endpoint bestaat niet op dit account.
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
}

Afleveringen opvragen

GET/v1/webhook_endpoints/{id}/deliveries

Elke poging van de afgelopen 30 dagen, nieuwste eerst: wat we stuurden, hoe je antwoordde en wanneer we het opnieuw proberen.

Scopewebhooks:write

Padparameters

idstringverplicht
De id van het endpoint.

Queryparameters

statusstring
Optioneel. succeeded, retrying of failed.
eventstring
Optioneel. Een event-id.
limit, cursor
Pagination

Fouten

StatusTypeWanneer
404not-foundDit endpoint bestaat niet op dit account.
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
}

Een aflevering opnieuw sturen

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

Stuurt het event nu, met dezelfde webhook-id, ongeacht de status. Al geplande herhalingen gaan door.

Scopewebhooks:write

Padparameters

idstringverplicht
De id van het endpoint.
deliverystringverplicht
Een afleverings-id.

Fouten

StatusTypeWanneer
404not-foundDit endpoint bestaat niet op dit account.
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"
}