Logotipo de NinjaBuyBusiness
Contactar con ventas
API de cuenta2026-11Vista previa

Endpoints de webhook

Las URL a las que enviamos eventos por POST. Los eventos, sus cargas, la firma y los reintentos están en Webhooks.
Endpoints

El objeto Webhook endpoint

idstring
Empieza por we_.
urlstring
Una URL https tuya que responda 2xx.
descriptionstring|null
Para ti.
events[]array
Los tipos de evento que se envían, o * para todos, incluidos los que se agreguen después: order.created, order.paid, order.bought, order.checked, order.shipped, product.cost_changed, product.out_of_stock, qc.issue.
statusstring
enabled, o disabled (por ti, o por nosotros tras cinco días en los que fallaron todas las entregas; antes te enviamos un correo).
api_versionstring
La versión en que se escriben las cargas de los eventos; la de la clave en el momento de crearlo.
secretstring
El secreto de firma. Solo en las respuestas de crear y rotar.
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"
}

Crear un endpoint

POST/v1/webhook_endpoints

Responde con el secreto de firma una sola vez: guárdalo ahora. Hasta 16 endpoints por cuenta.

Alcancewebhooks:write

Cuerpo

urlstringobligatorio
Solo https.
events[]arrayobligatorio
Tipos de evento, o ["*"].
descriptionstring
Opcional.

Errores

EstadoTipoCuándo
400bad-bodyLa URL no es https, o un tipo de evento es desconocido.
409invalid-stateLa cuenta ya tiene 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"
}

Listar endpoints

GET/v1/webhook_endpoints

Todos los endpoints de la cuenta, sin secretos.

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

Obtener un endpoint

GET/v1/webhook_endpoints/{id}

Un endpoint, sin su secreto.

Alcancewebhooks:write

Parámetros de ruta

idstringobligatorio
El id del endpoint.

Errores

EstadoTipoCuándo
404not-foundNo existe ese endpoint en esta cuenta.
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"
}

Actualizar un endpoint

PATCH/v1/webhook_endpoints/{id}

Cambia su URL o sus eventos, o desactívalo y actívalo. Al activarlo se envía lo que se perdió en los últimos 3 días.

Alcancewebhooks:write

Parámetros de ruta

idstringobligatorio
El id del endpoint.

Cuerpo

urlstring
Solo https.
events[]array
Tipos de evento, o ["*"].
descriptionstring
Opcional.
statusstring
Opcional. enabled o disabled.

Errores

EstadoTipoCuándo
404not-foundNo existe ese endpoint en esta cuenta.
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"
}

Eliminar un endpoint

DELETE/v1/webhook_endpoints/{id}

Detiene de inmediato todas las entregas hacia él, reintentos incluidos.

Alcancewebhooks:write

Parámetros de ruta

idstringobligatorio
El id del endpoint.

Errores

EstadoTipoCuándo
404not-foundNo existe ese endpoint en esta cuenta.
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 }

Rotar el secreto

POST/v1/webhook_endpoints/{id}/rotate_secret

Responde con un secreto nuevo. Durante 24 horas firmamos con ambos, así que el encabezado webhook-signature lleva dos firmas y cualquiera de ellas verifica: implementa el nuevo y deja que el anterior caduque.

Alcancewebhooks:write

Parámetros de ruta

idstringobligatorio
El id del endpoint.

Errores

EstadoTipoCuándo
404not-foundNo existe ese endpoint en esta cuenta.
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"
}

Enviar un evento de prueba

POST/v1/webhook_endpoints/{id}/test

Envía una muestra de un tipo de evento, firmada como cualquier otra, con test: true. Responde con lo que contestó tu endpoint.

Alcancewebhooks:write

Parámetros de ruta

idstringobligatorio
El id del endpoint.

Cuerpo

typestringobligatorio
Un tipo de evento.

Errores

EstadoTipoCuándo
404not-foundNo existe ese endpoint en esta cuenta.
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
}

Listar entregas

GET/v1/webhook_endpoints/{id}/deliveries

Cada intento de los últimos 30 días, del más reciente al más antiguo: qué enviamos, cómo respondiste y cuándo reintentamos.

Alcancewebhooks:write

Parámetros de ruta

idstringobligatorio
El id del endpoint.

Parámetros de consulta

statusstring
Opcional. succeeded, retrying o failed.
eventstring
Opcional. Un id de evento.
limit, cursor
Pagination

Errores

EstadoTipoCuándo
404not-foundNo existe ese endpoint en esta cuenta.
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
}

Volver a enviar una entrega

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

Envía el evento ahora, con el mismo webhook-id, sea cual sea su estado. Los reintentos ya programados continúan.

Alcancewebhooks:write

Parámetros de ruta

idstringobligatorio
El id del endpoint.
deliverystringobligatorio
Un id de entrega.

Errores

EstadoTipoCuándo
404not-foundNo existe ese endpoint en esta cuenta.
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"
}