Webhook mu polling mi? Eksikleri tamamlayabilen sipariş takibi

Olağan değişikliklerde webhook kullanın; kayıtlarınızın panelle eşleştiğini kontrol etmek için durum sorgularını koruyun. Güvenilir herkese açık alıcınız yoksa toplu polling ile başlayın.

Uygulama yeniden başlarken sipariş tamamlanabilir. Alındı yanıtı kaybolursa aynı olay iki kez gelebilir. Takip sistemi her iki durumu eski bilgi göstermeden veya güncellemeyi iki kez uygulamadan yönetmelidir.

Her yöntemin işi belli olsun

Polling: güncel durumu sorun

action=status sorgu anındaki durumu verir. Bir istekte 100 ID’ye kadar birleştirin. Kısa aralıklar, değişiklik olmasa bile daha fazla istek demektir.

Webhook: seçilen değişiklikleri alın

NotPanel olayları HTTPS adresinize gönderir. Bunlar istemcinin status istek kotasını kullanmaz; alıcı yine de kapasite ve izleme ister.

Mutabakat: eksik bilgiyi tamamlayın

Kesinti veya eski kayıt sonrasında ilgili siparişleri sorgulayın. Olaylar kaçırılabilir, denemeler sınırlıdır ve varış süresi garanti edilmez.

NotPanel API ne gönderir?

Endpoint’i dashboard’unuzun API sayfasından veya webhook.add ile ekleyin: herkese açık bir HTTPS URL ve ihtiyacınız olan olaylar; örneğin order.processing, order.in_progress, order.completed, order.partial, order.canceled, order.cancel_refused, refill.completed ve refill.rejected. Tam liste webhook referansındadır. secret değerini güvenle saklayın: yalnızca bir kez gösterilir ve webhook.list onu hiçbir zaman döndürmez. Endpoint’lerinizi webhook.list ile inceleyin, webhook.test ile test ping’i gönderin ve endpoint’i webhook.remove ile silin.

Her teslimat, kısa bir zarf içinde tek bir olay taşır: id, type, schema_version, created_at, sequence ve data. data.order, action=status yanıtıyla aynı alanlara sahiptir. Aşağıdaki kısaltılmış örnek gerçek bir sipariş değil, yalnızca biçimi gösterir.

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "order.completed",
  "schema_version": 1,
  "created_at": "2026-10-10T12:30:00Z",
  "sequence": 1042,
  "data": {
    "order": {
      "order": 7001,
      "status": "Completed",
      "status_key": "completed",
      "remains": "0"
    }
  }
}

Olay türünü doğrulanmış gövdeden okuyun. X-Webhook-Event de gönderilir ama imzalı değildir. Dashboard’dan ve API’den eklenen endpoint’ler aynı zarfı alır.

Olayları güvenle alın

1. Ham gövdeyi koruyun. secret ve X-Webhook-Timestamp kullanarak X-Webhook-Signature doğrulayın, kendi zaman toleransınızı uygulayın. Gövdeyi yeniden oluşturmak imzalanan baytları değiştirebilir.
2. Denemeleri izlemek için X-Webhook-Delivery-Id değerini kaydedin; o teslimatın her yeniden denemesinde aynı kalır. 2xx yanıtından önce doğrulanmış olayı kaydedin; güvenle kabul edemiyorsanız gönderenin yeniden denemesine izin verin.
3. Her olay id’sini bir kez işleyin. Tekrar denetimini yeniden başlatmalar boyunca, sipariş güncellemesiyle birlikte koruyun. Aynı olay id’si, o olaya abone olan her endpoint’e ulaşır.
4. Yavaş işleri kabulden sonra yapın. İmza gerçekliği doğrular, sıralamayı değil. Olayları sıralamak için sequence kullanın; geç gelen bir olay yeni durumla çelişirse değiştirmeden önce status sorgulayın.

İmza doğrulama rehberi

Alıcı kullanılamıyorsa ne olur?

Zaman aşımı (10 saniye) veya 2xx dışı yanıt başarısız bir denemedir. NotPanel her teslimatı 24 saat içinde en fazla 8 kez dener: hemen, sonra olaydan 1 dakika, 5 dakika, 30 dakika, 2 saat, 6 saat, 12 saat ve 24 saat sonra. Art arda 50 hata veya 3 gün boyunca hiç başarı olmazsa endpoint duraklatılır ve hesap sahibine bildirilir. Başarılı gönderim sayacı sıfırlar. webhook.list izleyin: sessizlik, değişiklik olmadığını kanıtlamaz.

Çözülmemiş veya eski siparişleri en fazla 100 ID’lik gruplarla düzenli kontrol edin; başlıklara ve sınırlara uyun. Alıcıyı düzelttikten sonra endpoint’i dashboard’unuzun API sayfasındaki webhook bölümünden yeniden başlatın; bu, hata sayacını sıfırlar. Alternatif olarak webhook.remove ile silip düzeltilmiş HTTPS URL’sini ve seçtiğiniz olayları webhook.add ile yeniden ekleyebilir, yeni secret değerini güvenle saklayıp alıcının doğrulamasını güncelleyebilirsiniz. Genel API, endpoint’i yeniden başlatan bir işlem sunmaz. Duraklatma anında kuyruktaki teslimatlar yeniden gönderilmez; kaçırılan sipariş durumlarını status ile uzlaştırın.

Başarılı gönderimin ötesini test edin

Yapay mesajlar ve kendi test secret değerinizi kullanın; müşteri siparişi gerekmez.

• Aynı gönderim iki kez gelince tek güncelleme olmalı.
• Aynı olay, arada yeniden başlatma olacak şekilde iki kez teslim edildiğinde yine tanınmalı.
• Bir bayt değişikliği veya eski zaman, politikanıza göre reddedilmeli.
• Kesinti ve gecikmiş olaydan sonra status güncel görünümü geri getirmeli.

Olay seçimi, secret doğrulaması ve hızlı onay için ayrıca GitHub webhook önerilerine bakın. Buradaki başlıklar, biçimler ve deneme sınırları NotPanel sözleşmesine aittir.

Sık sorulan sorular

Yalnızca polling kullanabilir miyim?

Evet. Sorguları gruplandırıp aralığı hacme ve sınırlara göre seçin. Sipariş oluşturmak veya takip etmek için webhook zorunlu değildir.

Webhook anında ve sadece bir kez mi gelir?

Hayır. Gecikme veya tekrar olabilir. Her gönderimi doğrulayın, her olayı bir kez işleyin ve kurtarma için durum sorgularını koruyun.

Hangi başlıkları kontrol etmeliyim?

X-Webhook-Signature ve X-Webhook-Timestamp değerlerini kontrol edin, ardından id, type ve data alanlarını doğrulanmış gövdeden okuyun. X-Webhook-Delivery-Id değerini yalnızca denemeleri izlemek için kullanın.

Webhook belirsiz bir add isteğini korur mu?

Bunlar farklı sorunlardır. add isteğini ilk request_id ve değişmeyen parametrelerle yineleyin, ardından bulunan sipariş ID’sini kaydedin.

Referanslar: webhook sözleşmesi · sipariş durumu · zaman aşımı kurtarma.