Webhooks

Webhooks, API görevleriniz tamamlandığında veya durumu değiştiğinde Meshy'den gerçek zamanlı güncellemeler almanızı sağlar. Yapılandırıldıktan sonra Meshy, belirttiğiniz URL'lere json formatında olay yükleri (payload) POST edecektir.

Webhook Oluşturmanın Nedenleri

Webhooks kullanmanın, özellikle API görev durumlarını otomatik olarak kontrol etme konusunda çeşitli avantajları vardır. Webhooks, görev durumu güncellemelerini almak için API'yi sürekli olarak yoklamaktan (polling) daha az çaba ve maliyet gerektirir. Webhooks ayrıca neredeyse gerçek zamanlı güncellemeler sağlar ve sonuçta API yoklamasından daha iyi ölçeklenir. Bu, özellikle sürekli yoklama yapıyorsanız, hız limitlerinizi daha iyi yönetmenizi de sağlar.

Kurulum & Yapılandırma

Webhooks'u etkinleştirmek için Geliştirici Platformu içindeki Webhooks sayfasını açın ve "Create Webhook" düğmesine tıklayın. Webhook almak istediğiniz https URL'sini girin ve Meshy'den görev güncellemelerini otomatik olarak almak için webhook'u etkinleştirin. Her Meshy hesabı için en fazla 5 aktif webhook'a sahip olabilirsiniz. Bir webhook etkinleştirildiğinde, tüm API görev durumu güncellemeleri otomatik olarak payload URL'sine gönderilir. Güvenlik amacıyla, şu anda yalnızca https URL'lerine webhook gönderilmesine izin veriyoruz. Yerel test yapılandırması yapmak isterseniz, aşağıdaki bölüme bakın.

Webhook Teslimat Gereksinimleri

Webhook'unuzun normal şekilde çalışması ve olayları almaya devam etmesi için:

Sunucunuz 400'ün altında bir HTTP durum kodu ile yanıt vermelidir (örn. 200 OK, 202 Accepted).
>= 400 durum koduna sahip herhangi bir yanıt, başarısız bir teslimat olarak değerlendirilecektir.
Art arda birden fazla başarısızlık:
- progress güncellemelerinin gecikmeli veya sırasız gelmesine neden olabilir
- Tekrarlanan denemelerden sonra webhook'unuzu otomatik olarak devre dışı bırakabilir (bkz. Otomatik Devre Dışı Bırakma Politikası)

İpucu: Daha ileri işleme asenkron olarak gerçekleşse bile, webhook yükünü doğruladıktan ve kaydettikten sonra her zaman bir başarı yanıtı döndürün.

Bir görevin son olayı, tipik süresinin yaklaşık iki katından sonra gelmediyse, görevi GET uç noktasıyla alın. Tipik süreler ve ne kadar beklenmesi gerektiği için Görev Yaşam Döngüsü sayfasına bakın.

Yerel Test için Webhook Yönlendirme

Webhook kodunuzu genellikle bir http adresinde olan yerel ortamda test etmek isterseniz, webhook'ları bilgisayarınıza veya codespace'inize yönlendirmek için bir webhook proxy URL kullanabilirsiniz. Aşağıda smee.io kullanılarak önerilen adımlar verilmiştir, ancak webhook proxy URL oluşturmak için istediğiniz herhangi bir hizmeti kullanabilirsiniz.

Bir webhook proxy URL alın:

Tarayıcınızda https://smee.io/ adresine gidin
"Start a new channel" seçeneğine tıklayın
"Webhook Proxy URL" altındaki tam URL'yi kopyalayın. Bu URL'yi aşağıdaki kurulum adımlarında kullanacaksınız.

Webhook'ları yönlendirin:

Eğer smee-client zaten yüklü değilse, terminalinizde aşağıdaki komutu çalıştırın.

npm install --global smee-client

smee.io'dan yönlendirilen webhook'ları almak için terminalinizde aşağıdaki komutu çalıştırın. WEBHOOK_PROXY_URL yerine daha önce aldığınız webhook proxy URL'nizi yazın.

smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

WEBHOOK_PROXY_URL'nin webhook proxy URL'niz olduğu şuna benzer bir çıktı görmelisiniz:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL

Webhook'unuzu test ederken bunu çalışır durumda tutun. Webhook yönlendirmeyi durdurmak istediğinizde Ctrl+C tuşlarına basın.
Yolun /webhook ve portun 3000 olduğunu unutmayın. Bu değerler, ileride webhook teslimatlarını almak için kendi kodunuzu kurmak istediğinizde işinize yarayabilir.

Bir webhook oluşturun:

Artık Webhooks sayfasında yeni bir webhook oluşturmak için webhook proxy URL'yi kullanabilirsiniz.

Örnek Yanıt

Bir görevin durumu değiştiğinde, Meshy yapılandırdığınız URL'ye bir webhook yükü POST eder. Yük, görev nesnesini JSON formatında içerir. Tüm görev nesnesi özelliklerinin ve örnek yüklerin tam açıklaması için şunlara bakın: