API Compte2026-11Aperçu

Endpoints de webhook

Les URL auxquelles nous envoyons les événements en POST. Les événements, leurs contenus, la signature et les nouvelles tentatives sont dans Webhooks.

Endpoints

POST/v1/webhook_endpointsCréer un endpoint
GET/v1/webhook_endpointsLister les endpoints
GET/v1/webhook_endpoints/{id}Récupérer un endpoint
PATCH/v1/webhook_endpoints/{id}Modifier un endpoint
DELETE/v1/webhook_endpoints/{id}Supprimer un endpoint
POST/v1/webhook_endpoints/{id}/rotate_secretRenouveler le secret
POST/v1/webhook_endpoints/{id}/testEnvoyer un événement de test
GET/v1/webhook_endpoints/{id}/deliveriesLister les livraisons
POST/v1/webhook_endpoints/{id}/deliveries/{delivery}/retryRenvoyer une livraison

L’objet Webhook endpoint

idstring: Commence par we_.
urlstring: Une URL https à vous qui répond 2xx.
descriptionstring|null: Pour vous.
events[]array: Les types d’événements à envoyer, ou * pour tous, y compris ceux ajoutés plus tard : order.created, order.paid, order.bought, order.checked, order.shipped, product.cost_changed, product.out_of_stock, qc.issue.
statusstring: enabled, ou disabled (par vous, ou par nous après cinq jours où chaque livraison a échoué ; nous vous prévenons par e-mail d’abord).
api_versionstring: La version dans laquelle sont écrits les contenus des événements ; celle de la clé à sa création.
secretstring: Le secret de signature. Uniquement dans les réponses à la création et au renouvellement.

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

Créer un endpoint

POST/v1/webhook_endpoints

Renvoie le secret de signature une seule fois : enregistrez-le tout de suite. Jusqu’à 16 endpoints par compte.

Scopewebhooks:write

Corps

urlstringobligatoire: https uniquement.
events[]arrayobligatoire: Types d’événements, ou ["*"].
descriptionstring: Facultatif.

Erreurs

Statut	Type	Quand
400	bad-body	L’URL n’est pas en https, ou un type d’événement est inconnu.
409	invalid-state	Le compte a déjà 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"
}

Lister les endpoints

GET/v1/webhook_endpoints

Tous les endpoints du compte, sans les 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
}

Récupérer un endpoint

GET/v1/webhook_endpoints/{id}

Un endpoint, sans son secret.

Scopewebhooks:write

Paramètres de chemin

idstringobligatoire: L’identifiant de l’endpoint.

Erreurs

Statut	Type	Quand
404	not-found	Aucun endpoint de ce type sur ce compte.

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

Modifier un endpoint

PATCH/v1/webhook_endpoints/{id}

Modifiez son URL ou ses événements, ou désactivez-le et réactivez-le. La réactivation envoie ce qu’il a manqué les 3 derniers jours.

Scopewebhooks:write

Paramètres de chemin

idstringobligatoire: L’identifiant de l’endpoint.

Corps

urlstring: https uniquement.
events[]array: Types d’événements, ou ["*"].
descriptionstring: Facultatif.
statusstring: Facultatif. enabled ou disabled.

Erreurs

Statut	Type	Quand
404	not-found	Aucun endpoint de ce type sur ce compte.

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

Supprimer un endpoint

DELETE/v1/webhook_endpoints/{id}

Arrête immédiatement toute livraison vers lui, nouvelles tentatives comprises.

Scopewebhooks:write

Paramètres de chemin

idstringobligatoire: L’identifiant de l’endpoint.

Erreurs

Statut	Type	Quand
404	not-found	Aucun endpoint de ce type sur ce compte.

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 }

Renouveler le secret

POST/v1/webhook_endpoints/{id}/rotate_secret

Renvoie un nouveau secret. Pendant 24 heures, nous signons avec les deux : l’en-tête webhook-signature porte deux signatures et l’une ou l’autre suffit. Déployez le nouveau, puis laissez l’ancien expirer.

Scopewebhooks:write

Paramètres de chemin

idstringobligatoire: L’identifiant de l’endpoint.

Erreurs

Statut	Type	Quand
404	not-found	Aucun endpoint de ce type sur ce compte.

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

Envoyer un événement de test

POST/v1/webhook_endpoints/{id}/test

Envoie un exemple d’un type d’événement, signé comme les autres, avec test: true. Renvoie la réponse de votre endpoint.

Scopewebhooks:write

Paramètres de chemin

idstringobligatoire: L’identifiant de l’endpoint.

Corps

typestringobligatoire: Un type d’événement.

Erreurs

Statut	Type	Quand
404	not-found	Aucun endpoint de ce type sur ce compte.

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
}

Lister les livraisons

GET/v1/webhook_endpoints/{id}/deliveries

Chaque tentative des 30 derniers jours, de la plus récente : ce que nous avons envoyé, ce que vous avez répondu et quand nous réessayons.

Scopewebhooks:write

Paramètres de chemin

idstringobligatoire: L’identifiant de l’endpoint.

Paramètres de requête

statusstring: Facultatif. succeeded, retrying ou failed.
eventstring: Facultatif. Un identifiant d’événement.
limit, cursor: Pagination

Erreurs

Statut	Type	Quand
404	not-found	Aucun endpoint de ce type sur ce compte.

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
}

Renvoyer une livraison

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

Envoie l’événement maintenant, avec le même webhook-id, quel que soit son état. Les nouvelles tentatives déjà prévues continuent.

Scopewebhooks:write

Paramètres de chemin

idstringobligatoire: L’identifiant de l’endpoint.
deliverystringobligatoire: Un identifiant de livraison.

Erreurs

Statut	Type	Quand
404	not-found	Aucun endpoint de ce type sur ce compte.

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