Webhook

Bir bakışta

NextPDF Enterprise, iş olaylarını kiracı başına webhook uç noktalarına HTTP POST üzerinden teslim eder, her yükü bir HMAC-SHA256 imzasıyla imzalar, üstel geri çekilme ile yeniden dener ve kalıcı olarak başarısız olan teslimleri inceleme ve yeniden oynatma için bir ölü-mektup kuyruğuna yönlendirir. Bu sayfa, gözlemlenebilir webhook davranışını ve genel sözleşmeyi açıklar.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) ile sevk edilir ve bir Enterprise katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans alın.

Webhook yüzeyi temel bir Enterprise yeteneğidir ve Enterprise paketi kurulduğunda kullanılabilir; özellik başına ayrı bir bayrak yoktur.

Kavramsal genel bakış

Bir kiracı, bir geri çağrı URL’si, bir imzalama gizli anahtarı ve isteğe bağlı bir olay türleri listesi kaydeder. Boş bir olay listesi “tüm olaylara abone ol” anlamına gelir. Kayıtlar kesinlikle kiracı kapsamlıdır: bir kiracı yalnızca kendi kayıtlarını görebilir ve yönetebilir; uyumsuz bir kiracı altında kayıt reddedilir. Kayıt silme, kaydı silmek yerine devre dışı bırakır; böylece geçmiş korunur; yalnızca etkin kayıtlar gönderim alır.

Bir kiracı için bir iş olayı gönderildiğinde, olay türüne abone olan her etkin kayıt bir teslim alır. Yük, standartlaştırılmış bir JSON belgesidir — benzersiz bir teslim tanımlayıcısı, iş tanımlayıcısı, olay türü, olay verisi, bir RFC 3339 zaman damgası ve kiracı tanımlayıcısı. Teslim, JSON gövdesini ve dört başlığı taşıyan bir HTTP POST’tur: bir HMAC-SHA256 imzası, bir unix-saniye zaman damgası, teslim tanımlayıcısı ve olay türü. İmza, kaydın gizli anahtarıyla {timestamp}.{body} kanonik temel dizesi üzerinde hesaplanır; böylece zaman damgası başlığı gövdeye kriptografik olarak bağlanır. Alıcı, HMAC’i aynı temel dize üzerinde yeniden hesaplar ve zaman damgası kabul edilebilir bir tazelik penceresinin dışına düşen teslimleri reddeder; bu, yeniden oynatmayı sınırlar.

Teslim, üstel geri çekilme kullanır. Bir 2xx yanıtı başarıdır. 429 dışında bir 4xx yanıtı, kalıcı bir reddetme olarak ele alınır ve yeniden denenmez. Diğer başarısızlıklar — 5xx, 429 veya bir bağlantı hatası — politikanın deneme sayısına kadar, bir maksimumda sınırlanan ikiye katlanan bir gecikmeyle yeniden denenir. Tüm denemeler tükendiğinde teslim, orijinal yük, deneme sayısı, son hata ve son HTTP durumuyla bellek içi bir ölü-mektup kuyruğuna kaydedilir; bir ölü-mektup girişi yeniden oynatılmış olarak işaretlenebilir. İki yeniden deneme politikası sevk edilir — bir default (5 deneme, 1s temel, 5dk sınır) ve bir aggressive (10 deneme, 2s temel, 10dk sınır).

Neden bu şekilde çalışır

Teslim, ateşle-ve-unut bir çağrı değil, operasyonel bir yüzey olarak ele alınır. Başarısızlıklar niyete göre sınıflandırılır. 429 dışında bir 4xx gerçek bir alıcı reddidir, bu yüzden hemen durur. Bir 5xx, bir 429 veya bir bağlantı hatası geçicidir, bu yüzden sınırlanan, geri çekilen bir yeniden deneme kazanır. Her denemeyi tüketen teslimler asla sessizce düşürülmez; yeniden oynatılabilen incelenebilir bir ölü-mektup kuyruğuna inerler. İmza, temel dizesine bir zaman damgası bağlar ve her hedef bir çıkış geçidini geçer; böylece özgünlük ve yeniden oynatma direnci her kiracı için yapı gereği korunur.

Tasarım arka planı: NextPDF’i üretimde işletme.

Genel API yüzeyi

composer require nextpdf/enterprise:^3

Desteklenen entegrasyon noktaları şunlardır: webhook yöneticisi (register, unregister, activeRegistrations, dispatch), kayıt değer nesnesi (subscribesTo, deactivate), yük (fromJobEvent, toJson, toArray, sign, signedTimestamp), teslim motoru (deliver, deadLetters, clearDeadLetters), yeniden deneme politikası (delayForAttempt, shouldRetry, default, aggressive) ve ölü-mektup girişi (markReplayed).

Kod örneği — hızlı başlangıç

use NextPDF\Enterprise\Webhook\WebhookManager;
use NextPDF\Enterprise\Webhook\WebhookRegistration;

$manager->register($tenant, new WebhookRegistration(
    id: $id,
    tenantId: $tenant->tenantId,
    url: 'https://customer.example.com/hooks/nextpdf',
    events: [],            // empty = subscribe to all event types
    secret: $signingSecret,
));

$delivered = $manager->dispatch($tenant, $jobEvent); // count of successes

Alıcı tarafı doğrulama:

$ts = (int) $request->header('X-NextPDF-Timestamp');
if (abs(time() - $ts) > 300) {
    return new Response(401); // stale timestamp: reject to bound replay
}
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $rawBody, $sharedSecret);
if (! hash_equals($expected, $request->header('X-NextPDF-Signature'))) {
    return new Response(401);
}

Kod örneği — üretim

use NextPDF\Enterprise\Webhook\WebhookDelivery;
use NextPDF\Enterprise\Webhook\WebhookRetryPolicy;

$delivery = new WebhookDelivery(
    $httpClient, $requestFactory, $streamFactory,
    retryPolicy: WebhookRetryPolicy::aggressive(), // 10 attempts, 2s base, 10min cap
    logger: $logger,
);

$manager = new WebhookManager($delivery, $logger);
$manager->dispatch($tenant, $jobEvent);

foreach ($delivery->deadLetters() as $dead) {
    $this->scheduleReplay($dead); // inspect last error + last HTTP status
}

Uç durumlar ve tuzaklar

• Boş olay listesi tümüne abone olur. Olay türü olmayan bir kayıt, her olayı alır; kapsamlandırmak için açık bir liste geçirin.
• Kiracı yalıtımı zorlanır. Bağlam kiracısından farklı bir kiracı kimliğiyle kayıt reddedilir; gönderim yalnızca çağıran kiracının etkin kayıtlarında yinelenir.
• 4xx (429 hariç) nihaidir. 429 dışında bir 4xx yeniden denenmez — kalıcı bir alıcı reddi olarak ele alınır ve ölü-mektup kuyruğuna gider.
• Kayıt silme yumuşaktır. Kayıt silme, devre dışı bırakır; kayıt korunur ve gönderimden çıkarılır.
• Ölü-mektup kuyruğu bellek içidir. Süreç ömrü içinde inceleme ve yeniden oynatma içindir; yeniden başlatmalar arası kalıcı yeniden oynatmaya ihtiyacınız varsa girişleri kendiniz kalıcılaştırın.

Performans

Gönderim maliyeti, kiracı için olaya abone olan etkin kayıtların sayısıyla orantılıdır. Her teslim, imzalı temel dize üzerinde bir HMAC-SHA256 artı HTTP gidiş-dönüşüdür; yeniden denemeler, sınırlı üstel-geri çekilme gecikmeleri ekler. İmzalama O(yük boyutu)‘dur.

Güvenlik notları

Her yük, kaydın gizli anahtarıyla anahtarlanmış bir HMAC-SHA256 imzasıyla kimliği doğrulanır ve X-NextPDF-Signature başlığında sha256=<hex> olarak gönderilir. İmza, {timestamp}.{body} temel dizesini kapsar ve zaman damgası X-NextPDF-Timestamp başlığında taşınır; alıcılar sabit zamanlı bir karşılaştırmayla doğrular ve yeniden oynatmayı sınırlamak için bir tazelik penceresinin dışındaki teslimleri reddeder. Hedef URL’ler her gönderimden önce merkezî bir çıkış geçidini geçer: HTTPS gereklidir ve özel, geri döngü, bağlantı-yerel veya bulut-meta veri adreslerine çözümlenen ana bilgisayarlar bir istek olmadan reddedilir ve ölü-mektup kuyruğuna yönlendirilir. İmzalama gizli anahtarı kayıt başınadır; onu bir kimlik bilgisi olarak ele alın. İmza, yük bütünlüğünü ve kökeni doğrular; bir şifreleme katmanı değildir — alıcının görmemesi gereken olay verisine gizli bilgi koymayın.

Uygunluk

• Yük kimlik doğrulaması, SHA-256 ile HMAC, FIPS PUB 198-1’in anahtarlı-karma mesaj kimlik doğrulama kodunu kullanır; OWASP ASVS 5.0, HMAC-SHA-256’yı onaylanmış mesaj kimlik doğrulama algoritmaları arasında listeler.
• Yük zaman damgaları RFC 3339 tarih-saat dizeleridir. Not: RFC 3339 bu sayfa için RAG bütüncesinden alınmamıştır; biçim kodda bildirilmiştir (RFC 3339 genişletilmiş) ve RAG-doğrulanmış değil, kodda-bildirilmiş olarak işaretlenmiştir.

Davranış sözleşmesi

• Kayıtlar kesinlikle kiracı kapsamlıdır; uyumsuz bir kiracı altında kayıt reddedilir ve kayıt silme, geçmişi koruyan yumuşak bir devre dışı bırakmadır.
• Boş bir olay listesi tüm olaylara abone olur; yalnızca olay türüne abone olan etkin kayıtlar bir gönderim alır.
• Her teslim, JSON gövdesi artı bir HMAC-SHA256 imza başlığı ({timestamp}.{body} temel dizesi üzerinde), bir unix-saniye zaman damgası başlığı, teslim tanımlayıcısı ve olay türüyle bir HTTP POST’tur.
• Bir 2xx başarıdır; 429 dışında bir 4xx kalıcı bir reddetmedir (yeniden deneme yok); 5xx, 429 veya bir bağlantı hatası, politikanın deneme sayısına kadar sınırlanmış ikiye katlanan geri çekilme ile yeniden denenir.
• Tükenmiş denemeler, teslimi bellek içi bir ölü-mektup kuyruğuna kaydeder (yük, deneme sayısı, son hata, son durum); bir ölü-mektup girişi yeniden oynatılmış olarak işaretlenebilir.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahilî ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Core yedeği

NextPDF Core (Apache-2.0) hiçbir webhook kaydı veya teslim yüzeyine sahip değildir — hiçbiri; bu yeteneğin Core katmanında bir eşdeğeri yoktur.

Pro yedeği

NextPDF Pro hiçbir webhook kaydı veya teslim yüzeyine sahip değildir — hiçbiri; bu yeteneğin Pro katmanında bir eşdeğeri yoktur. Webhook yöneticisi, kayıt, yük, teslim motoru ve yeniden deneme politikası yalnızca nextpdf/enterprise paketinde sevk edilir.

Enterprise sınır notu

Yeniden deneme politikası, geri çekilme zamanlaması ve ölü-mektup işleme, davranış düzeyinde açıklanmıştır. Ölü-mektup kuyruğu, süreç ömrü içinde inceleme ve yeniden oynatma için bellek içidir; kalıcı, yeniden başlatmalar arası kalıcılaştırma ve herhangi bir dahilî teslim dahilîsi, genel yüzeyin kapsamı dışındadır.

Dağıtım sınırı

Operatör; geri çağrı uç noktalarına, kayıt başına imzalama gizli anahtarlarına (kimlik bilgisi olarak ele alınır), yeniden başlatmalar arası yeniden oynatma gerekiyorsa ölü-mektup girişlerinin kalıcı kalıcılaştırılmasına ve alıcı URL’lerinin HTTPS duruşuna sahiptir. NextPDF Enterprise imzalar ve teslim eder, ancak kayıtları veya ölü mektupları süreç ömrünün ötesinde kendisi kalıcılaştırmaz.

Hukuki uygunluk sınırı

Webhook yüzeyine hiçbir ihracat kontrolü kısıtlaması uygulanmaz. HMAC imzası, yük bütünlüğünü ve kökeni doğrular; bir şifreleme katmanı değildir — operatörler, alıcının görmemesi gereken olay verisine gizli bilgi koymamalıdır. Bu belge bir hukuki görüş değildir; kendi uygunluk ve hukuk danışmanlarınıza başvurun.

Ayrıca bakınız

• Webhook — derin referans
• SaaS — NextPDF Enterprise
• Metering — NextPDF Enterprise
• Licensing — NextPDF Enterprise