NinjabuyのロゴBusiness
営業に問い合わせる
アカウントAPI2026-11プレビュー

Webhookエンドポイント

当社がイベントをPOSTするURL。イベント、ペイロード、署名、再試行はWebhookにあります。
エンドポイント

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

署名シークレットは一度だけ返されます。今すぐ保存してください。1アカウントあたり最大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}

エンドポイント1つ（シークレットなし）。

スコープ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ヘッダーには署名が2つ入り、どちらでも検証できます。新しいものをデプロイし、古いものは期限切れにしてください。

スコープ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

1つのイベントタイプのサンプルを、他と同じように署名し 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"
}