Webhooks

Webhooks, API görevleriniz tamamlandığında veya durum değiştirdiğ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 eder.

Neden Webhooks Oluşturmalısınız

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 yoklamaktan daha az çaba ve maliyet gerektirir. Webhooks ayrıca neredeyse gerçek zamanlı güncellemeler sağlar ve nihayetinde API yoklamasından daha iyi ölçeklenir. Bu da özellikle sürekli yoklama yapıyorsanız hız sınırlarınızı daha iyi yönetmenizi sağlar.

Kurulum ve Yapılandırma

Webhooks'u etkinleştirmek için Meshy web uygulamasında oturum açtığınızda API ayarları sayfasına gidin. API key'lerinizin altındaki "Webhooks" bölümünü bulun ve "Create Webhook" düğmesine tıklayın. Meshy'den webhook almak için istediğiniz https URL'yi sağlayın ve Meshy'den görev güncellemelerini otomatik olarak almak üzere webhook'u etkinleştirin. Meshy hesabı başına en fazla 5 etkin webhook'unuz olabilir. Bir webhook etkinleştirildiğinde, tüm API görev durumu güncellemeleri otomatik olarak payload URL'ye gönderilir. Güvenlik amacıyla, şu anda yalnızca https URL'lere webhook gönderilmesine izin veriyoruz. Yerel testi yapılandırmak isterseniz aşağıdaki bölüme bakın.

Webhook Teslim Gereksinimleri

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

  • Sunucunuzun 400'ün altında bir HTTP durum kodu ile yanıt vermesi gerekir (örn. 200 OK, 202 Accepted).
  • Durum kodu >= 400 olan herhangi bir yanıt başarısız teslim olarak değerlendirilecektir.
  • Birden fazla ardışık başarısızlık:
    • progress güncellemelerinin gecikmesine veya sıra dışı gelmesine neden olabilir
    • Tekrarlanan denemelerden sonra webhook'unuzu otomatik olarak devre dışı bırakabilir (bkz. Otomatik Devre Dışı Bırakma Politikası)

İpucu: Daha fazla işleme eşzamansız olarak gerçekleşse bile, webhook yükünü doğrulayıp depoladıktan sonra her zaman başarılı bir yanıt döndürün.

Yerel Test için Webhooks Yönlendirme

Genellikle bir http adresinde olan webhook kodunuzu yerel olarak test etmek isterseniz, webhooks'u bilgisayarınıza veya codespace'inize yönlendirmek için bir webhook proxy URL kullanabilirsiniz. Aşağıdakiler smee.io kullanılarak önerilen adımlardır, ancak webhook proxy URL oluşturmak için istediğiniz herhangi bir hizmeti kullanabilirsiniz.

webhook proxy URL alın:

  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.

Webhooks'u yönlendirin:

  1. smee-client zaten yüklü değilse terminalinizde aşağıdaki komutu çalıştırın.
npm install --global smee-client
  1. smee.io'dan yönlendirilen webhooks'u almak için terminalinizde aşağıdaki komutu çalıştırın. WEBHOOK_PROXY_URL değerini daha önceki webhook proxy URL'nizle değiştirin.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

WEBHOOK_PROXY_URL değerinin webhook proxy URL'niz olduğu, buna benzeyen bir çıktı görmelisiniz:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Webhook'unuzu test ederken bunu çalışır durumda tutun. Webhooks yönlendirmeyi durdurmak istediğinizde Ctrl+C girin.
    Yolun /webhook ve portun 3000 olduğunu unutmayın. Bu değerler, daha sonra webhook teslimlerini almak için kendi kodunuzu ayarlamak istediğinizde işinize yarayabilir.

Bir webhook oluşturun:

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

Örnek Yanıt

Bir görev durumu değiştiğinde Meshy, yapılandırılmış URL'nize 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 eksiksiz açıklaması için bkz.: