Webhook yönetimi API'si

Webhook'lar, eşzamansız (asynchronous) bir görev tamamlandığında, başarısız olduğunda veya zaman aşımına uğradığında uygulamanızı bilgilendirir. Bunları Dashboard → API → Webhooks üzerinden, Management API aracılığıyla veya TokenLab MCP'nin full profili üzerinden yapılandırabilirsiniz. Webhook'lar aynı çalışma alanı (workspace) uç noktalarını ve teslimat geçmişini paylaşır.

Hangi kimlik bilgisi kullanılmalıCopy Anchor Link

Dashboard → API → Management Tokens üzerinden bir Management Token oluşturun. Token'lar çalışma alanı kapsamlıdır: görevleri gönderen API anahtarıyla aynı çalışma alanını seçin. Bir token, başka bir çalışma alanının uç noktalarını okuyamaz veya değiştiremez. API anahtarları ve signing secret'lar, Management API tarafından reddedilir. Dashboard yapılandırması, oturum açmış olduğunuz çalışma alanı yönetici oturumunuzu kullanır.

mt-… ve whsec_… değerlerini arka ucunuzda (backend) saklayın. Bunları tarayıcı kodlarına, istemlere (prompt), depo dosyalarına veya URL'lere gömmeyin. Management Token'lar diğer çalışma alanı yönetimi işlemlerini de yetkilendirir; sadece webhook'lara özel kimlik bilgileri değildirler.

Bir uç nokta yapılandırmaCopy Anchor Link

export TOKENLAB_MANAGEMENT_TOKEN="mt-your-management-token"
curl https://api.tokenlab.sh/v1/management/webhooks \
  -H "Authorization: Bearer $TOKENLAB_MANAGEMENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-app.example/webhooks/tokenlab","events":["task.completed","task.failed","task.timeout"],"description":"Production task results"}'

201 yanıtı, id ve whsec_ ile başlayan tek kullanımlık bir secret içerir. Bu adımı tamamlamadan önce secret'ı kaydedin. Listeleme/getirme/güncelleme yanıtları bunu asla göstermez. Çalışma alanı başına en fazla 10 uç nokta yapılandırılabilir. URL'ler herkese açık HTTPS kullanmalı ve kimlik bilgileri, sorgu dizeleri veya fragmanlar içeremez. Yönlendirmeler (redirects) takip edilmez.

PATCH {"is_active":false} ile duraklatın; PATCH {"is_active":true} ile devam ettirin. Devam ettirmek, ardışık hata sayacını sıfırlar. Döndürme (rotation) işlemi yeni bir secret'ı bir kez döndürür; bunu hemen alıcınızda yapılandırın. İşlemdeki istekler önceki imzayı taşıyor olabilir, bu nedenle döndürme sırasında her iki secret'ı da kısa bir süreliğine kabul edin. Döndürme işlemi geri alınamaz.

Etkinlikler ve yükler (payloads)Copy Anchor Link

Abonelikler, gelecekteki terminal eşzamansız görev etkinliklerini kapsar; eşzamanlı sonuçlar ve geçmiş görevler tekrar oynatılmaz (replayed). Seçilen etkinlik türleri için tüm çalışma alanı görevlerini alın ve data.taskId değerini, görevi oluşturduğunuzda dönen ID ile eşleştirin. Geri arama (callback) alanları camelCase kullanır; yönetim yanıt alanları snake_case kullanır.

{
  "id": "event-unique-id",
  "type": "task.completed",
  "created": 1790000000,
  "data": {
    "taskType": "video",
    "taskId": "ldtask_0123456789abcdef0123456789abcdef",
    "model": "your-selected-model",
    "durationMs": 42000,
    "resultUrls": ["https://api.tokenlab.sh/v1/media-results/7c9e6679-7425-40de-944b-e07fc1f90ae7.mp4?token=…"],
    "settledCost": 0.12
  }
}

resultUrls içindeki her giriş, 30 gün boyunca geçerli olan bir TokenLab medya sonucu URL'sidir. Bkz. Veri saklama.

task.timeout için expectedTimeoutMs yapılandırılmış zaman aşımı eşiğidir ve actualWaitMs geçen bekleme süresidir, her ikisi de milisaniye cinsindendir. refundIssued: true, iadenin başarılı olduğu veya zaten yapıldığı anlamına gelir; false olması, daha sonra iade yapılmayacağı anlamına gelmez. refundOutcome, iade işleme sonucunu açıklar. Zaman aşımı etkinlikleri durationMs içermez.

Alanlar göreve bağlıdır ve bulunmayabilir. Yetkili sonuç ve faturalandırma durumu için orijinal çalışma alanının sk-… anahtarıyla GET /v1/tasks/{id} kullanın. Bir etkinliğin retryable değeri, oluşturma hatasını açıklar; bu, terminal durumundaki bir görevi süresiz olarak yoklamanız veya otomatik olarak yeni bir faturalandırılabilir görev göndermeniz için bir talimat değildir. task.failed içinde error, errorCode ve retryable değerleri, görevin herkese açık error_details.message, code ve retryable değerleridir; bunlar durum sorgulamasının döndürdüğü değerlerle aynıdır.

İşlemeden önce doğrulayınCopy Anchor Link

Her POST isteği X-Webhook-ID, X-Webhook-Timestamp (Unix saniye) ve X-Webhook-Signature (sha256=<hex>) içerir. Tam whsec_… secret'ını kullanarak tam zaman damgası dizesi, bir nokta ve ham istek gövdesi baytları üzerinde HMAC-SHA256 hesaplayın. Doğrulamadan önce JSON'ı ayrıştırmayın ve yeniden serileştirmeyin.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody, headers, secrets) {
  const timestamp = headers['x-webhook-timestamp'];
  const signature = headers['x-webhook-signature'];
  if (typeof timestamp !== 'string' || !/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  if (typeof signature !== 'string' || !/^sha256=[a-f0-9]{64}$/.test(signature)) return false;
  const received = Buffer.from(signature.slice(7), 'hex');
  return secrets.some(secret => {
    const expected = createHmac('sha256', secret).update(timestamp + '.').update(rawBody).digest();
    return timingSafeEqual(expected, received);
  });
}

Doğrulamadan sonra, gövdedeki id değerinin X-Webhook-ID ile eşleştiğini kontrol edin, etkinlik ID'sini iş öğenizle atomik olarak kalıcı hale getirin ve hızlıca 2xx yanıtı dönün. Ağır işleri kendi kuyruğunuzdan işleyin. Alıcı uç noktada etkinlik ID'sine göre tekilleştirme (deduplication) yapın: teslimatlar tekrarlanabilir ve sıralama garanti edilmez. Beş dakikalık zaman damgası toleransı, tekrar oynatma (replay) yaşını sınırlar; ID tekilleştirme, bu pencere içinde tekrarlanan işlemleri önler.

Yeniden denemeler ve kurtarmaCopy Anchor Link

Her teslimat döngüsü, önce 1 saniye, sonra 4 saniye bekleyerek üç denemeye kadar işlem yapar. Her HTTP denemesinin 10 saniyelik bir zaman aşımı ve yeni bir zaman damgası/imzası vardır. Ağ hataları, 429 ve 5xx hataları yeniden denenebilir. Diğer 4xx hataları, yönlendirmeler ve geçersiz ağ hedefleri, yeniden denemeden o döngüyü durdurur. Geçici hatalar, aynı teslimat ID'si ile daha sonra etkinlik yeniden denemelerini tetikleyebilir. Ardışık on başarısız döngü, uç noktayı otomatik olarak duraklatır.

outcome, http_status, attempts ve delivered_at değerlerini görmek için test işlemini ve teslimat geçmişini kullanın. Başarılı bir test API yanıtı (200), yalnızca denemenin kaydedildiği anlamına gelir: outcome == "delivered" olup olmadığını kontrol edin. Alıcıyı düzeltin, uç noktayı devam ettirin ve ardından başka bir test gönderin. Geçmiş, yükleri değil teslimat meta verilerini içerir; eski etkinliklerin manuel olarak tekrar oynatılması mümkün değildir. Görev ID'lerini saklayın ve alıcınız duraklatılmış veya kullanılamaz durumdaysa görev durumuyla mutabakat sağlayın.

MCP yapılandırmasıCopy Anchor Link

Webhook yönetim araçları full profilinde mevcuttur. Yönetim kimlik bilgisi, çıkarım (inference) anahtarından ayrıdır; katalog ve webhook yönetimi, çıkarım anahtarı olmadan çalışabilir.

{
  "mcpServers": {
    "tokenlab": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server@latest"],
      "env": {
        "TOKENLAB_MCP_TOOL_PROFILE": "full",
        "TOKENLAB_MANAGEMENT_TOKEN": "mt-your-management-token",
        "TOKENLAB_API_KEY": "sk-your-inference-key"
      }
    }
  }
}

Araçlar: list_webhooks, create_webhook, get_webhook, update_webhook, delete_webhook, rotate_webhook_secret, test_webhook, list_webhook_deliveries. Kimlik bilgilerini asla bir araç argümanına yapıştırmayın. Yönetim erişimini yalnızca güvenilir MCP istemcilerine verin.

Yoklama (Polling) yedeğiCopy Anchor Link

Webhook'lar, durum sorgulama erişimini kaldırmaz veya yeni bir yoklama sınırı getirmez. Yoklama yapıyorsanız, oluşturma yanıtındaki poll_url değerini kullanın, bekleme durumundayken aralıkları artırın (back off) ve terminal durumlarında durun. 401, 403, 404 veya error.retryable == false durumlarında durun; geçici 503 async_task_owner_unavailable hatalarını aralık artırarak yeniden deneyin. Eksik veya süresi dolmuş bir görev 404 async_task_not_found döndürür. Eksik bir görevi tekrar tekrar sorgulamak onu yeniden oluşturamaz.

Seedance uyumluluk API'sinin callback_url değeri, istek başına ayrı bir geri arama sözleşmesidir. Bu görev oluşturulurken ayarlanabilir; bu çalışma alanı etkinlik yüklerini veya HMAC başlıklarını kullanmaz.