شعار NinjaBuyالأعمال
تواصل مع المبيعات
Account API2026-11إصدار تجريبي

نقاط نهاية webhook

عناوين URL التي نرسل إليها الأحداث بـ POST. الأحداث وحمولاتها وتوقيعها وإعادة المحاولات في Webhooks.
نقاط النهاية

كائن Webhook endpoint

idstring
يبدأ بـ we_.
urlstring
رابط https لك يرد بـ 2xx.
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 (بواسطتك، أو بواسطتنا بعد خمسة أيام فشلت فيها كل عمليات التسليم، ونرسل إليك بريدًا أولًا).
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-bodyعنوان URL ليس 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مطلوب
معرّف نقطة النهاية.

الأخطاء

الحالةالنوعمتى
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}

غيّر عنوانها أو أحداثها، أو عطّلها وفعّلها. التفعيل يرسل ما فاتها في آخر 3 أيام.

النطاقwebhooks:write

معاملات المسار

idstringمطلوب
معرّف نقطة النهاية.

النص

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مطلوب
معرّف نقطة النهاية.

الأخطاء

الحالةالنوعمتى
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مطلوب
معرّف نقطة النهاية.

الأخطاء

الحالةالنوعمتى
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مطلوب
معرّف نقطة النهاية.

النص

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مطلوب
معرّف نقطة النهاية.

معاملات الاستعلام

statusstring
اختياري. succeeded أو retrying أو failed.
eventstring
اختياري. معرّف حدث.
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مطلوب
معرّف نقطة النهاية.
deliverystringمطلوب
معرّف عملية تسليم.

الأخطاء

الحالةالنوعمتى
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"
}