Ninjabuy 로고Business
영업팀에 문의
계정 API2026-11프리뷰

웹훅 엔드포인트

저희가 이벤트를 POST하는 URL. 이벤트, 페이로드, 서명, 재시도는 웹훅에 있어요.
엔드포인트

Webhook endpoint 객체

idstring
we_로 시작해요.
urlstring
2xx로 응답하는 내 https URL.
descriptionstring|null
내게.
events[]array
보낼 이벤트 유형, 또는 나중에 추가되는 유형을 포함한 전체는 *: order.created, order.paid, order.bought, order.checked, order.shipped, product.cost_changed, product.out_of_stock, qc.issue.
statusstring
enabled 또는 disabled(내가 비활성화했거나, 5일 동안 모든 전송이 실패해 저희가 비활성화한 경우. 먼저 이메일로 알려 드려요).
api_versionstring
이벤트 페이로드가 작성되는 버전. 생성 시 키의 버전.
secretstring
서명 시크릿. 생성과 교체 응답에만 있어요.
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"
}

엔드포인트 생성

POST/v1/webhook_endpoints

서명 시크릿은 한 번만 반환돼요. 지금 저장하세요. 계정당 최대 16개 엔드포인트.

범위webhooks:write

본문

urlstring필수
https만.
events[]array필수
이벤트 유형 또는 ["*"].
descriptionstring
선택 사항.

오류

상태유형시점
400bad-bodyURL이 https가 아니거나 알 수 없는 이벤트 유형이 있어요.
409invalid-state이 계정에는 이미 엔드포인트가 16개 있어요.
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"
}

엔드포인트 목록

GET/v1/webhook_endpoints

계정의 모든 엔드포인트, 시크릿 제외.

범위webhooks: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
}

엔드포인트 조회

GET/v1/webhook_endpoints/{id}

엔드포인트 하나, 시크릿 제외.

범위webhooks:write

경로 매개변수

idstring필수
엔드포인트 ID.

오류

상태유형시점
404not-found이 계정에 해당 엔드포인트가 없어요.
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"
}

엔드포인트 수정

PATCH/v1/webhook_endpoints/{id}

URL이나 이벤트를 변경하거나 비활성화·활성화해요. 활성화하면 최근 3일 동안 놓친 것을 보내요.

범위webhooks:write

경로 매개변수

idstring필수
엔드포인트 ID.

본문

urlstring
https만.
events[]array
이벤트 유형 또는 ["*"].
descriptionstring
선택 사항.
statusstring
선택 사항. enabled 또는 disabled.

오류

상태유형시점
404not-found이 계정에 해당 엔드포인트가 없어요.
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"
}

엔드포인트 삭제

DELETE/v1/webhook_endpoints/{id}

재시도를 포함해 그곳으로의 모든 전송을 즉시 멈춰요.

범위webhooks:write

경로 매개변수

idstring필수
엔드포인트 ID.

오류

상태유형시점
404not-found이 계정에 해당 엔드포인트가 없어요.
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 }

시크릿 교체

POST/v1/webhook_endpoints/{id}/rotate_secret

새 시크릿을 반환해요. 24시간 동안은 둘 다로 서명하므로 webhook-signature 헤더에 서명이 두 개 들어가고 어느 쪽으로든 검증돼요. 새 시크릿을 배포한 뒤 이전 것은 만료되게 두세요.

범위webhooks:write

경로 매개변수

idstring필수
엔드포인트 ID.

오류

상태유형시점
404not-found이 계정에 해당 엔드포인트가 없어요.
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"
}

테스트 이벤트 보내기

POST/v1/webhook_endpoints/{id}/test

한 이벤트 유형의 샘플을 다른 이벤트처럼 서명하고 test: true를 붙여 보내요. 엔드포인트의 응답을 반환해요.

범위webhooks:write

경로 매개변수

idstring필수
엔드포인트 ID.

본문

typestring필수
이벤트 유형.

오류

상태유형시점
404not-found이 계정에 해당 엔드포인트가 없어요.
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
}

전송 목록

GET/v1/webhook_endpoints/{id}/deliveries

최근 30일의 모든 시도, 최신순: 보낸 내용, 내 응답, 다음 재시도 시점.

범위webhooks:write

경로 매개변수

idstring필수
엔드포인트 ID.

쿼리 매개변수

statusstring
선택 사항. succeeded, retrying 또는 failed.
eventstring
선택 사항. 이벤트 ID.
limit, cursor
Pagination

오류

상태유형시점
404not-found이 계정에 해당 엔드포인트가 없어요.
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
}

전송 다시 보내기

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

상태와 관계없이 같은 webhook-id로 지금 이벤트를 보내요. 이미 예약된 재시도는 계속돼요.

범위webhooks:write

경로 매개변수

idstring필수
엔드포인트 ID.
deliverystring필수
전송 ID.

오류

상태유형시점
404not-found이 계정에 해당 엔드포인트가 없어요.
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"
}