TTS ve Video API'leri için Webhook Entegrasyon Rehberi

Uzun süren işler (video üretimi, toplu sesli kitap oluşturma) istek thread'inizi bloklamamalı. Webhook'lar cevap.

Speeko Webhook'ları Nasıl Çalışır

1. Bir webhook_url ile iş gönderirsiniz
2. Speeko hemen bir job_id döndürür
3. İş tamamlandığında Speeko URL'nize POST eder
4. Endpoint'iniz sonucu doğrular ve işler

Endpoint Gereksinimleri

• Genel HTTPS URL — HTTP yok, localhost yok (dev için ngrok kullanın)
• 10 saniye içinde yanıt verir — Yoksa Speeko başarısız işaretler ve yeniden dener
• 2xx durumu döndürür — Başka herhangi bir şey yeniden denemeyi tetikler
• Idempotent yönetim — Aynı webhook iki kez tetiklenebilir

Örnek Webhook Handler (Node.js)

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/speeko', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-speeko-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Geçersiz imza');
  }

  const event = JSON.parse(req.body);

  if (await alreadyProcessed(event.job_id)) {
    return res.status(200).send('Zaten işlendi');
  }

  await processJob(event);
  await markProcessed(event.job_id);

  res.status(200).send('OK');
});

İmza Doğrulama

Her Speeko webhook'u, gövdenin HMAC-SHA256'sını içeren bir X-Speeko-Signature başlığı içerir. İşlemeden önce her zaman doğrulayın.

Yeniden Deneme Politikası

Endpoint'iniz başarısız olursa, Speeko üstel backoff ile yeniden dener:

• Yeniden deneme 1: 1 dakika sonra
• Yeniden deneme 2: 5 dakika sonra
• Yeniden deneme 3: 30 dakika sonra
• Yeniden deneme 4: 2 saat sonra
• Yeniden deneme 5: 8 saat sonra

5 başarısızlıktan sonra webhook terk edilir. Durum için /v1/jobs/:id endpoint'ini kullanın.

Idempotency

Webhook'lar aynı olay için birden çok kez tetiklenebilir. Handler'ınız yinelenenleri tolere etmeli. job_id'yi idempotency anahtarı olarak kullanın.

Yerel Geliştirme

ngrok http 3000

ngrok URL'sini webhook_url olarak kullanın.

Debug

Speeko'nun dashboard'u istek/yanıt detaylarıyla webhook teslim geçmişini gösterir. Başarısız teslimleri debug etmek için kullanın.

Yaygın Tuzaklar

• Yavaş endpoint (>10sn yanıt) → başarısız olarak işlenir
• İmzayı doğrulamayı unutmak → güvenlik açığı
• Idempotency yok → çift ücretlendirme, yinelenen bildirimler
• Senkron downstream çağrılar → başarısızlık zinciri

Webhook'larınızı kurun.