تخطَّ إلى المحتوى
مطوّرو دكانالتوثيق
Englishتسجيل الدخول

Webhooks

4 عمليات

GET/webhooks#

Read this install's webhook subscription

النطاق غير معلن في المواصفة

The signing secret is never returned; it can only be rotated.

المعاملات

لا معاملات.

الاستجابات

200

The active subscription, or null when none is configured

الاسمالنوعالوصف
dataمطلوبيقبل nullWebhookSubscription

One subscription per install; PUT is a full replace.

  • 401

    Missing, invalid, expired, or revoked token

  • 429

    Token budget exhausted (180 requests/minute, 60 writes/minute per install)

الطلب
curl -X GET "https://dukkan.one/platform-api/v1/webhooks" \
  -H "Authorization: Bearer $DUKKAN_ACCESS_TOKEN"
الاستجابة
{
  "data": {
    "id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
    "endpoint_url": "string",
    "topics": [
      "order.created"
    ],
    "status": "active",
    "consecutive_failures": 1,
    "activated_at": "2026-08-18T16:00:00Z",
    "disabled_at": "2026-08-18T16:00:00Z",
    "secret": "string"
  }
}

PUT/webhooks#

Create or replace this install's webhook subscription

النطاق غير معلن في المواصفة

One endpoint per install; a PUT fully replaces the topic list. The signing secret is returned EXACTLY ONCE — on creation, or when rotate_secret is true — and can never be read back afterwards. Topics are scope-gated: subscribing to a topic requires the read scope that governs its payload. endpoint_url must be a public HTTPS URL.

المعاملات

لا معاملات.

جسم الطلب مطلوب

Create or replace the install's single subscription.

الاسمالنوعالوصف
endpoint_urlمطلوبstring

Public HTTPS URL. Private, loopback and IP-literal hosts are refused.

topicsمطلوبWebhookTopic[]
rotate_secretboolean

Mint a new signing secret and return it once in the response.

الاستجابات

200

Subscription created or replaced; secret present only when minted

الاسمالنوعالوصف
dataمطلوبWebhookSubscription

One subscription per install; PUT is a full replace.

  • 400

    Invalid request

  • 401

    Missing, invalid, expired, or revoked token

  • 403

    Required live scope is missing

  • 404

    Resource not found in the token-bound store

  • 429

    Token budget exhausted (180 requests/minute, 60 writes/minute per install)

الطلب
curl -X PUT "https://dukkan.one/platform-api/v1/webhooks" \
  -H "Authorization: Bearer $DUKKAN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "endpoint_url": "https://app.example.com/webhooks/dukkan",
  "topics": [
    "order.created"
  ],
  "rotate_secret": false
}'
الاستجابة
{
  "data": {
    "id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
    "endpoint_url": "string",
    "topics": [
      "order.created"
    ],
    "status": "active",
    "consecutive_failures": 1,
    "activated_at": "2026-08-18T16:00:00Z",
    "disabled_at": "2026-08-18T16:00:00Z",
    "secret": "string"
  }
}

DELETE/webhooks#

Stop delivery for this install

النطاق غير معلن في المواصفة

المعاملات

لا معاملات.

الاستجابات

204

Subscription revoked

لا جسم للاستجابة.

  • 401

    Missing, invalid, expired, or revoked token

  • 429

    Token budget exhausted (180 requests/minute, 60 writes/minute per install)

الطلب
curl -X DELETE "https://dukkan.one/platform-api/v1/webhooks" \
  -H "Authorization: Bearer $DUKKAN_ACCESS_TOKEN"
الاستجابة
{
  "error": {
    "code": "invalid_request",
    "message": "A human-readable explanation",
    "request_id": "req_01J8Z1K5X9",
    "details": {}
  }
}

POST/webhooks/test#

Fire one signed test delivery (sandbox stores only)

النطاق غير معلن في المواصفة

Writes a real outbox event for the topic, built from the sandbox store's own records (overridable through data), fans it out to this install's subscription and lets the delivery worker sign and send it with the same secret and SSRF checks as production traffic. The envelope carries test: true. Requires an active subscription that includes the topic and the scope that governs it. Budget: 30 per ten minutes per install. Answers 403 sandbox_required on real stores, 409 webhook_not_subscribed / webhook_topic_not_subscribed / sample_unavailable when the rehearsal cannot be built.

المعاملات

لا معاملات.

جسم الطلب مطلوب

Fire one signed test delivery (sandbox stores only).

الاسمالنوعالوصف
topicمطلوبWebhookTopic

Webhook topic. Subscribing needs the read scope that governs the payload; app.uninstalled needs none and still delivers after revocation.

القيم:order.createdorder.status_changedorder.paidproduct.createdproduct.updatedproduct.deletedinventory.movement_createdfulfillment.requestedfulfillment.createdfulfillment.updatedrefund.createdapp.uninstalled
dataobject

Optional overrides merged over the platform-built sample payload for the topic (at most 16 KB).

الاستجابات

202

Event written and fanned out; the worker sends within about a minute

الاسمالنوعالوصف
dataمطلوبWebhookTestEvent

The accepted test event and its queued deliveries.

  • 400

    Invalid request

  • 401

    Missing, invalid, expired, or revoked token

  • 403

    Required live scope is missing

  • 409

    State transition, inventory, refund, or idempotency conflict

  • 413

    Override data exceeds 16 KB

  • 429

    Token budget exhausted (180 requests/minute, 60 writes/minute per install)

الطلب
curl -X POST "https://dukkan.one/platform-api/v1/webhooks/test" \
  -H "Authorization: Bearer $DUKKAN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "order.created",
  "data": {}
}'
الاستجابة
{
  "data": {
    "event_id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
    "topic": "order.created",
    "sequence": 1661,
    "occurred_at": "2026-08-18T16:00:00Z",
    "test": true,
    "data": {},
    "deliveries": [
      {
        "id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
        "status": "pending",
        "endpoint_url": "string"
      }
    ]
  }
}