AiVideoEditor
Ücretsiz başlayın
Menü

İnceleme 2026-11-11 · API sürümü 2026-11-09 · Markdown oku

Müşteri webhook'ları

Çalışma alanınız için giden olay teslimi. Bir HTTPS uç noktası kaydedin, tek kullanımlık imzalama gizli anahtarını doğrulayın ve sınırlı yeniden denemelerle imzalı olaylar alın.

Uç nokta kaydetme

curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
  • İmzalama gizli anahtarı (whsec_…) bir kez döndürülür: ilk başarılı oluşturma yanıtında. Saklayın; aynı oluşturmanın idempotent yeniden oynatımı uç noktayı gizli anahtar olmadan döndürür ve bir daha gösterilemez.
  • Hedefler HTTPS, herkese açık şekilde çözümlenebilir ve gömülü kimlik bilgisi içermeyen olmalıdır. Özel, loopback, link-local (bulut üst verisi dâhil), unique-local ve multicast adreslerine yapılan istekler, hiçbir bağlantı kurulmadan önce reddedilir ve yönlendirmeler asla takip edilmez.
  • Kayıt, o uç nokta için eventTypes filtresinden bağımsız olarak hedefli bir webhook.verification olayı kuyruğa ekler. Sıradan olaylar, uç noktanız doğrulamayı 2xx ile yanıtladıktan sonra akmaya başlar.

Teslimatları doğrulama

Her istek şunları taşır:

BaşlıkAnlam
x-publisher-event-idKararlı olay kimliği: yeniden denemeler ve yeniden oynatmalar arasında özdeş
x-publisher-event-typeOlay türü, ör. post.published
x-publisher-timestampUnix saniyeleri
x-publisher-signaturet=<ts>,v1=<hex>

İmza; imzalama gizli anahtarınız kullanılarak ${t}.${event_id}.${raw_body} üzerinden HMAC-SHA256'dır. ±300 saniyelik toleransla doğrulayın ve dışındaki yeniden oynatmaları reddedin. Node örneği:

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

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Ayrıştırmadan önce her zaman ham istek gövdesine karşı doğrulayın.

Olay zarfı

{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}

Başlangıç olay kataloğu (genişletilebilir; kayıtta eventTypes filtreler):

  • webhook.verification: doğrulama yükü; uç noktayı etkinleştirmek için 2xx yanıtlayın
  • post.published: yerel makbuzla doğrulanmış tek hedef
  • delivery.failed: son olarak başarısız olan tek hedef
  • delivery.requires_action: onay/yeniden bağlantı/geç inceleme gerekiyor

Toplam gönderi sonuçları (post.partially_published, post.failed) henüz üretilmiyor; yalnızca bir üretici var olduğunda burada belgelenir, bu nedenle onlara güvenmeyin. Yukarıdaki hedef başına olaylara abone olun ve toplu durumu gönderinin teslimat sonuçlarından türetin.

Yeniden denemeler, yeniden oynatma ve devre dışı bırakma

  • Denemeler: hemen, ardından +1m, +5m, +30m, +2h, +8h. Yeniden denemeler, güvenli biçimde tekilleştirebilmeniz için aynı olay kimliğini ve bayt düzeyinde özdeş gövdeyi yeniden kullanır.
  • 2xx = teslim edildi. 429/5xx/zaman aşımı yeniden denenir. Diğer 4xx'ler o olay için kalıcı olarak başarısız olur (uç noktayı düzeltin, sonra yeniden oynatın).
  • 410 Gone uç noktayı devre dışı bırakır: ona başka olay kuyruğa eklenmez.
  • İç webhook servisi üzerinden operatör yetkili yeniden oynatma, olayı özgün kimliğiyle yeniden gönderir. Aktif kiralanmış bir yürütülmekte olan deneme asla geri alınmaz; yeniden oynatma, olayın meşgul olduğunu ve kısa süre içinde yeniden denenebileceğini bildirir.

Operasyonel notlar

  • Teslimat tanılamaları yalnızca güvenli sonuç kodları saklar: asla sizin gizli anahtarınızı, imzaları, istek başlıklarını veya yanıt gövdelerini değil. Yükler ayrıca temizlenir: kuyruğa alınmadan önce sağlayıcı/OAuth gizli anahtarları ve medya ön-imza URL'leri çıkarılır.
  • Uç noktalar çalışma alanı kapsamlıdır: başka bir çalışma alanından bir uç nokta UUID'sine sahip olmak hiçbir şey yapmaz.
  • Teslim, kabul edilen her olay gerçekleşimi için en az bir kezdir; x-publisher-event-id üzerinde tekilleştirin.

Geliştirici araçlarının kullanılabilirliği

Developers sayfası; çalışma alanı API anahtarlarını ve webhook uç noktalarını imzalama-gizli anahtarı şifreleme yapılandırmasından bağımsız listeler. Webhook oluşturmak, geçerli bir sunucu şifreleme yapılandırması gerektirir; yapılandırma uyarısını çözmek için dağıtım operatörüne danışın. API anahtarı yönetimi kullanılabilir kalır. Mevcut imzalama gizli anahtarları bir daha asla gösterilmez.