Logo NinjabuyBusiness
Contatta le vendite
API Account2026-11Anteprima

Endpoint webhook

Gli URL a cui inviamo gli eventi in POST. Eventi, payload, firma e nuovi tentativi sono in Webhook.
Endpoint

L’oggetto Webhook endpoint

idstring
Inizia con we_.
urlstring
Un tuo URL https che risponde 2xx.
descriptionstring|null
Per te.
events[]array
I tipi di evento da inviare, o * per tutti, inclusi quelli aggiunti in futuro: order.created, order.paid, order.bought, order.checked, order.shipped, product.cost_changed, product.out_of_stock, qc.issue.
statusstring
enabled, o disabled (da te, o da noi dopo cinque giorni in cui ogni consegna è fallita; prima ti inviamo un’email).
api_versionstring
La versione in cui sono scritti i payload degli eventi; quella della chiave alla creazione.
secretstring
Il segreto di firma. Solo nelle risposte a creazione e rotazione.
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"
}

Crea un endpoint

POST/v1/webhook_endpoints

Restituisce il segreto di firma una sola volta: salvalo subito. Fino a 16 endpoint per account.

Scopewebhooks:write

Corpo

urlstringobbligatorio
Solo https.
events[]arrayobbligatorio
Tipi di evento, o ["*"].
descriptionstring
Facoltativo.

Errori

StatoTipoQuando
400bad-bodyL’URL non è https, o un tipo di evento è sconosciuto.
409invalid-stateL’account ha già 16 endpoint.
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"
}

Elenca gli endpoint

GET/v1/webhook_endpoints

Ogni endpoint dell’account, senza segreti.

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
}

Recupera un endpoint

GET/v1/webhook_endpoints/{id}

Un endpoint, senza il suo segreto.

Scopewebhooks:write

Parametri di percorso

idstringobbligatorio
L’ID dell’endpoint.

Errori

StatoTipoQuando
404not-foundNessun endpoint simile su questo 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"
}

Aggiorna un endpoint

PATCH/v1/webhook_endpoints/{id}

Cambia il suo URL o gli eventi, o disattivalo e riattivalo. La riattivazione invia ciò che ha perso negli ultimi 3 giorni.

Scopewebhooks:write

Parametri di percorso

idstringobbligatorio
L’ID dell’endpoint.

Corpo

urlstring
Solo https.
events[]array
Tipi di evento, o ["*"].
descriptionstring
Facoltativo.
statusstring
Facoltativo. enabled o disabled.

Errori

StatoTipoQuando
404not-foundNessun endpoint simile su questo 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"
}

Elimina un endpoint

DELETE/v1/webhook_endpoints/{id}

Ferma subito ogni consegna verso di esso, nuovi tentativi inclusi.

Scopewebhooks:write

Parametri di percorso

idstringobbligatorio
L’ID dell’endpoint.

Errori

StatoTipoQuando
404not-foundNessun endpoint simile su questo 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 }

Ruota il segreto

POST/v1/webhook_endpoints/{id}/rotate_secret

Restituisce un nuovo segreto. Per 24 ore firmiamo con entrambi, quindi l’intestazione webhook-signature contiene due firme e ognuna è valida: distribuisci il nuovo, poi lascia scadere il vecchio.

Scopewebhooks:write

Parametri di percorso

idstringobbligatorio
L’ID dell’endpoint.

Errori

StatoTipoQuando
404not-foundNessun endpoint simile su questo 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"
}

Invia un evento di test

POST/v1/webhook_endpoints/{id}/test

Invia un esempio di un tipo di evento, firmato come gli altri, con test: true. Restituisce come ha risposto il tuo endpoint.

Scopewebhooks:write

Parametri di percorso

idstringobbligatorio
L’ID dell’endpoint.

Corpo

typestringobbligatorio
Un tipo di evento.

Errori

StatoTipoQuando
404not-foundNessun endpoint simile su questo 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
}

Elenca le consegne

GET/v1/webhook_endpoints/{id}/deliveries

Ogni tentativo degli ultimi 30 giorni, dal più recente: cosa abbiamo inviato, come hai risposto e quando riproviamo.

Scopewebhooks:write

Parametri di percorso

idstringobbligatorio
L’ID dell’endpoint.

Parametri di query

statusstring
Facoltativo. succeeded, retrying o failed.
eventstring
Facoltativo. Un ID di evento.
limit, cursor
Pagination

Errori

StatoTipoQuando
404not-foundNessun endpoint simile su questo 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
}

Invia di nuovo una consegna

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

Invia l’evento ora, con lo stesso webhook-id, qualunque sia il suo stato. I nuovi tentativi già programmati continuano.

Scopewebhooks:write

Parametri di percorso

idstringobbligatorio
L’ID dell’endpoint.
deliverystringobbligatorio
Un ID di consegna.

Errori

StatoTipoQuando
404not-foundNessun endpoint simile su questo 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"
}