Logo da NinjabuyBusiness
Falar com vendas
API de conta2026-11Prévia

Endpoints de webhook

As URLs para as quais enviamos eventos via POST. Os eventos, os payloads, a assinatura e as novas tentativas estão em Webhooks.
Endpoints

O objeto Webhook endpoint

idstring
Começa com we_.
urlstring
Uma URL https sua que responda 2xx.
descriptionstring|null
Para você.
events[]array
Os tipos de evento a enviar, ou * para todos, inclusive os adicionados depois: order.created, order.paid, order.bought, order.checked, order.shipped, product.cost_changed, product.out_of_stock, qc.issue.
statusstring
enabled, ou disabled (por você, ou por nós depois de cinco dias em que todas as entregas falharam; enviamos um e-mail antes).
api_versionstring
A versão em que os payloads dos eventos são escritos; a da chave no momento da criação.
secretstring
O segredo de assinatura. Só nas respostas de criar e rotacionar.
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"
}

Criar um endpoint

POST/v1/webhook_endpoints

Responde com o segredo de assinatura uma única vez: guarde agora. Até 16 endpoints por conta.

Escopowebhooks:write

Corpo

urlstringobrigatório
Só https.
events[]arrayobrigatório
Tipos de evento, ou ["*"].
descriptionstring
Opcional.

Erros

StatusTipoQuando
400bad-bodyA URL não é https, ou um tipo de evento é desconhecido.
409invalid-stateA conta já tem 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 os endpoints da conta, sem segredos.

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

Obter um endpoint

GET/v1/webhook_endpoints/{id}

Um endpoint, sem o segredo.

Escopowebhooks:write

Parâmetros de caminho

idstringobrigatório
O id do endpoint.

Erros

StatusTipoQuando
404not-foundEsse endpoint não existe nesta conta.
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"
}

Atualizar um endpoint

PATCH/v1/webhook_endpoints/{id}

Altere a URL ou os eventos, ou desative e ative. Ao ativar, enviamos o que ele perdeu nos últimos 3 dias.

Escopowebhooks:write

Parâmetros de caminho

idstringobrigatório
O id do endpoint.

Corpo

urlstring
Só https.
events[]array
Tipos de evento, ou ["*"].
descriptionstring
Opcional.
statusstring
Opcional. enabled ou disabled.

Erros

StatusTipoQuando
404not-foundEsse endpoint não existe nesta conta.
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"
}

Excluir um endpoint

DELETE/v1/webhook_endpoints/{id}

Interrompe na hora todas as entregas para ele, inclusive as novas tentativas.

Escopowebhooks:write

Parâmetros de caminho

idstringobrigatório
O id do endpoint.

Erros

StatusTipoQuando
404not-foundEsse endpoint não existe nesta conta.
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 }

Rotacionar o segredo

POST/v1/webhook_endpoints/{id}/rotate_secret

Responde com um novo segredo. Por 24 horas assinamos com os dois, então o cabeçalho webhook-signature traz duas assinaturas e qualquer uma valida: implante o novo e deixe o antigo expirar.

Escopowebhooks:write

Parâmetros de caminho

idstringobrigatório
O id do endpoint.

Erros

StatusTipoQuando
404not-foundEsse endpoint não existe nesta conta.
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 um evento de teste

POST/v1/webhook_endpoints/{id}/test

Envia uma amostra de um tipo de evento, assinada como qualquer outra, com test: true. Responde com o que o seu endpoint respondeu.

Escopowebhooks:write

Parâmetros de caminho

idstringobrigatório
O id do endpoint.

Corpo

typestringobrigatório
Um tipo de evento.

Erros

StatusTipoQuando
404not-foundEsse endpoint não existe nesta conta.
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 tentativa dos últimos 30 dias, da mais recente para a mais antiga: o que enviamos, como você respondeu e quando tentamos de novo.

Escopowebhooks:write

Parâmetros de caminho

idstringobrigatório
O id do endpoint.

Parâmetros de consulta

statusstring
Opcional. succeeded, retrying ou failed.
eventstring
Opcional. Um id de evento.
limit, cursor
Pagination

Erros

StatusTipoQuando
404not-foundEsse endpoint não existe nesta conta.
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
}

Enviar uma entrega de novo

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

Envia o evento agora, com o mesmo webhook-id, qualquer que seja o estado. As novas tentativas já programadas continuam.

Escopowebhooks:write

Parâmetros de caminho

idstringobrigatório
O id do endpoint.
deliverystringobrigatório
Um id de entrega.

Erros

StatusTipoQuando
404not-foundEsse endpoint não existe nesta conta.
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"
}