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?
Bu rehber webhook.add ile kaydedilen endpoint içindir: herkese açık HTTPS URL ve order.processing, order.in_progress, order.completed, order.partial, order.refunded, order.refill_completed gibi desteklenen olaylar. Dönen secret değerini saklayın; webhook.list bunu döndürmez. Durum ve hataları webhook.list ile inceleyin, kaydı webhook.remove ile silin.
API gönderimi, tek olayda bile events dizisi içerir. Her öğenin id, event, timestamp ve data alanları vardır; deliveryId gönderimi tanımlar. Kısaltılmış örnek açıklama içindir. Eski zamanları güncellik testi için kullanmayın.
{
"events": [
{
"id": "EXAMPLE_EVENT_ID",
"event": "order.completed",
"timestamp": 1700000000,
"data": { "order": 7001, "status_key": "completed" }
}
],
"timestamp": 1700000001,
"deliveryId": "EXAMPLE_DELIVERY_ID"
}Olay adını doğrulanmış gövdeden okuyun; API grupları X-Webhook-Event gerektirmez. Dashboard üzerinden oluşturulan webhook farklı, tek olaylı biçim kullanır; biçimleri birbirinin yerine kullanmayın.
Özgün gövdedeki imzayı ve zaman damgasını doğrulayın.
2xx yanıtını vermeden önce doğrulanmış gönderimi kaydedin.
Her olayı bir kez uygulayın; eksikleri durum sorgularıyla tamamlayın.
Olayları güvenle alın
- 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.
- X-Webhook-Delivery-Id değerini imzalı gövdedeki deliveryId ile eşleştirin. 2xx yanıtından önce kaydedin; güvenle kabul edemiyorsanız gönderenin yeniden denemesine izin verin.
- Her events[].id değerini bir kez işleyin. Tekrar denetimini yeniden başlatmalar boyunca, sipariş güncellemesiyle birlikte koruyun. Aynı olay farklı endpoint üzerinden gelebilir.
- Yavaş işleri kabulden sonra yapın. İmza gerçekliği doğrular, sıralamayı değil. Geç olay yeni durumla çelişirse değiştirmeden önce status sorgulayın.
Alıcı kullanılamıyorsa ne olur?
Zaman aşımı veya 2xx dışı yanıt hata sayılır. NotPanel artan aralıklarla dener ve art arda 10 hatada API endpoint kaydını duraklatır; 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. Duraklatılan alıcıyı düzelttikten sonra kaydın active olduğunu doğrulayın. Geçmişte başarısız tüm gönderimlerin kendiliğinden tekrarlanacağını varsaymayı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ı.
- Bir olay iki grupta ve yeniden başlatma sonrasında yinelenmemeli.
- 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. X-Webhook-Delivery-Id ile doğrulanmış gövdedeki deliveryId değerini eşleştirip events dizisini işleyin.
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.
