Abonelik

Uygulamanız kendi aboneliklerini API üzerinden yönetir. Yalnızca kendi oluşturduğu abonelikleri görür ve değiştirir — tüccarın kendi aboneliklerini ya da başka bir uygulamanınkileri asla.

Oluşturma — POST /apps/webhooks/subscriptions (write_webhooks)

{
  "url": "https://hooks.your-app.example/ciqra",
  "eventTypes": ["order.paid", "order.shipped"],
  "description": "Fulfilment sync"
}

Alan	Kural
url	Mutlak URL, en fazla 2048 karakter, özel (private) bir adres olamaz. https kullanın.
eventTypes	Zorunlu, boş olamaz. Her biri, kurulumunuzun scope’larının (yetkilerinin) almasına izin verdiği bilinen bir olay olmalıdır (büyük/küçük harf duyarsız) — order.* için read_orders gerekir, vb.
description	İsteğe bağlı, en fazla 256 karakter.

Bir secret göndermezsiniz: teslimatlar, kurulum sırasında aldığınız kurulumunuza ait imzalama secret’ı (ciqra_ss_…) ile imzalanır. Yanıt 200:

{
  "id": "…", "url": "https://hooks.your-app.example/ciqra", "description": "Fulfilment sync",
  "eventTypes": ["order.paid", "order.shipped"], "isActive": true, "hasSigningSecret": true,
  "isDeliverable": true, "createdAt": "…", "updatedAt": null, "installationId": "…"
}

Doğrulama hataları {"error": "…"} ile 400 döner. Alamayacağınız bir olayı istemek, eksik scope’u adıyla belirtir:

{ "error": "This installation cannot receive: order.paid (needs read_orders)." }

Boş bir eventTypes reddedilir: bir uygulama yalnızca adı verilen olaylara abone olur; böylece platforma eklenen yeni bir olay türü, tüccarın o izni vermediği bir uygulamaya asla ulaşmaz.

Listeleme — GET /apps/webhooks/subscriptions (read_webhooks)

Bu kurulumun aboneliklerini, yukarıdaki nesnenin bir dizisi olarak döndürür.

Kaldırma — DELETE /apps/webhooks/subscriptions/{id} (write_webhooks)

204; abonelik sizin değilse 404. O abonelik için kuyruğa alınmış teslimatlar düşürülür.

Güncelleme endpoint’i yoktur: bir URL’yi ya da olay listesini değiştirmek için önce yeni aboneliği oluşturun, sonra eskisini silin; böylece arada hiçbir olay kaybolmaz.

Uygulama kaldırıldığında

Kurulumun tüm abonelikleri devre dışı bırakılıp kaldırılır ve kuyruktaki teslimatlar düşürülür. Kaldırmadan sonra hiçbir şey teslim edilmez.