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üklerini POST edecektir.

Neden Webhook Oluşturulmalı

Webhook kullanmanın, özellikle API görev durumlarını otomatik olarak kontrol etme konusunda çeşitli avantajları vardır. Webhookler, görev durumu güncellemelerini almak için API'yi sürekli yoklamaktan daha az çaba ve maliyet gerektirir. Webhookler ayrıca neredeyse gerçek zamanlı güncellemelere olanak tanır ve nihayetinde 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 ve Yapılandırma

Webhookleri 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 webhooku etkinleştirin. Her Meshy hesabı başına 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

Webhookunuzun normal şekilde çalışması ve olayları almaya devam etmesi için:

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

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

Yerel Test için Webhook Yönlendirme

Webhook kodunuzu genellikle http adresinde olan yerel ortamınızda test etmek isterseniz, webhookleri 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 dilediğiniz herhangi bir servisi kullanabilirsiniz.

Webhook proxy URL edinin:

  1. Tarayıcınızda https://smee.io/ adresine gidin
  2. "Start a new channel" düğmesine tıklayın
  3. "Webhook Proxy URL" altındaki tam URL'yi kopyalayın. Bu URL'yi aşağıdaki kurulum adımlarında kullanacaksınız.

Webhookleri yönlendirin:

  1. smee-client zaten kurulu değilse, terminalinizde aşağıdaki komutu çalıştırın.
npm install --global smee-client
  1. smee.io'dan yönlendirilen webhookleri 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 aşağıdakine benzer bir çıktı görmelisiniz:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Webhookunuzu test ederken bunu çalışır durumda tutun. Webhookleri yönlendirmeyi durdurmak istediğinizde Ctrl+C tuşlarına basın.
    Yolun /webhook ve portun 3000 olduğunu unutmayın. Daha sonra webhook teslimatlarını almak için kendi kodunuzu kurmak istediğinizde bu değerler işinize yarayabilir.

Webhook oluşturun:

Artık Webhooks sayfasında yeni bir webhook oluşturmak için webhook proxy URL'sini 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 edecektir. Yük, JSON formatında görev nesnesini içerir. Tüm görev nesnesi özelliklerinin ve örnek yüklerin eksiksiz bir açıklaması için şu sayfalara bakın: