Web kancaları

Ürününüzü webhook etkinliklerine hazırlayın.

Kullanım, faturalandırma ve API önemli yaşam döngüsü etkinlikleri için müşteri web kancası uç noktaları oluşturun ve yönetin, ardından alıcıları imzalı teslimat, yeniden denemeler ve düzeltilmiş gözlemlenebilirlik için hazırlayın.

Uç nokta yapılandırma İmzaları doğrulayın

Son güncelleme: July 12, 2026. Examples kullanım safe placeholders ve yap değil içerir real gizli bilgiler, API anahtarıs, veya customer yükler.

Alıcı kuralı

Alıcıları önce ham yük imzasını doğrulamaya hazırlayın, her olay kimliğini bir kez kaydedin ve yalnızca uygulamanız olayı güvenli bir şekilde işleyebildiğinde veya yok sayabildiğinde 2xx'i döndürün.

Kurulum yolu

URL uç noktasından teslimat hazırlığına kadar olmakş adım.

Step 1

Alıcı uç noktası oluşturma

POST isteklerini kabul eden ve JSON ayrıştırmadan önce ham istek gövdesini okuyabilen bir HTTPS URL ortaya çıkarın.

Açık

Step 2

Etkinlikleri seçin

Alıcınızın hazır olması gereken kullanım, abonelik, fatura veya API temel yaşam döngüsü olay türlerini seçin.

Açık

Step 3

İmza sırrını saklayın

Uç nokta sırrını bir kez kopyalayın ve bir gizli yöneticiye kaydedin; böylece alıcılar imzalı web kancası teslimine hazır olur.

Açık

Step 4

İşlemeyi yeniden denemeyi planla

Webhook gönderimi etkinleştirildiğinde tekrarlanan teslimat girişimlerinin güvenli olmasını sağlayacak şekilde bağımsız alıcılar tasarlayın.

Açık

Step 5

Gözlemlenebilirliği planlayın

Uç nokta durumunu şimdi izleyin ve ekibinizin gelecekteki webhook gönderimi içiçinde ihtiyaç duyacağı teslimat kayıtlarını tanımlayın.

Açık

Uç nokta URL

Ortam başına bir uç nokta kaydedin.

Gelecekteki test teslimatlarının hiçbir zaman üretim yan etkilerini tetiklememesi içiçinde geliştirme, hazırlama ve üretim içiçinde ayrı URL'ler kullanın.

{
  "name": "Production usage events",
  "url": "https://example.com/api/unlimitedcodex/webhook",
  "events": [
    "usage.threshold_reached",
    "subscription.updated",
    "invoice.payment_failed"
  ]
}

Etkinlik seçimi

Alıcınızın hazır olması gereken olay türlerini seçin.

Teslimat hazırlanırken her alıcıyı dar tutun. Bir faturalandırma hizmeti yalnızca fatura olaylarına ihtiyaç duyabilirken, bir kullanım korkuluğu yalnızca eşik olay fikstürlerine ihtiyaç duyabilir.

Webhook olayları, tetikleyici bağlamı ve alıcı kullanım durumları.
Etkinlik	Tetikleyici bağlam	Alıcı kullanım durumu
kullanım.threshold_reached	Bir çalışma alanı, yapılandırılmış bir kullanım eşiğini aşıyor.	Hesap sahibi mesajlarını hazırlayın, pahalı işleri duraklatın veya fatura sahiplerinden paketin uygunluğunu incelemelerini isteyin.
abonelik.güncellendi	Abonelik durumu, paket veya fatura dönemi değişiklikleri.	Yerel yetkileri ve erişim ayrıntılarını yenileyin.
api_key.iptal edildi	Bir API anahtarı iptal edildi.	Önbelleğe alınmış kimlik bilgilerini geçersiz kılın ve sahip olan ekip bildirimi hazırlayın.
fatura.ödenmiş	Bir fatura ödendi olarak işaretlenir.	Ücretli erişimin kilidini açın, fatura durumunu mutabakata varın veya hesap kayıtlarını güncelleyin.
fatura.payment_failed	Fatura ödemesi başarısız oluyor.	Riskli arka planda kullanıma yönelik bir ihtar akışı, hesap sahibi mesajları veya sınırlamalar hazırlayın.

Gizli imza

İşlemeden önce ham gövdeyi doğrulayın.

Webhook imzalama sırları bir kez gösterilir. Gizli anahtarı bir ortam değişkeninde veya gizli kod yöneticisinde saklayın, ardından web kancası gönderimi etkinleştirildiğinde zaman damgalı HMAC SHA-256 imzalarını yapğrulamak içiçinde bunu kullanın.

signature value kullanır t=timestamp,v1=signature. Bu example names header x-ucx-signature; kullanım signature header shown içiçinde sizin teslimat.

import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.split("="))
  );
  const timestamp = Number(parts.t);
  const signature = parts.v1;

  if (!Number.isInteger(timestamp) || !signature) {
    return false;
  }

  const signedPayload = `${timestamp}.${rawBody}`;
  const expected = createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");
  const left = Buffer.from(expected, "hex");
  const right = Buffer.from(signature, "hex");

  return left.length === right.length && timingSafeEqual(left, right);
}

Alıcı örneği

İşleyicileri küçük ve önemsiz tutun.

Giden teslimat etkinleştirildiğinde bu alıcı modelini kullanın: imza doğrulamasından sonra olayı ayrıştırın, etkinlik kimliğini kaydedin ve ardından yavaş çalışmayı kendi kuyruğunuza aktarın.

export async function POST(request) {
  const rawBody = await request.text();
  const signature = request.headers.get("x-ucx-signature") ?? "";
  const secret = process.env.UCX_WEBHOOK_SECRET;

  if (!secret || !verifySignature(rawBody, signature, secret)) {
    return new Response("Invalid signature", { status: 400 });
  }

  const event = JSON.parse(rawBody);

  // Store event.id before doing side effects so retries stay idempotent.
  await recordWebhookEvent(event.id, event.type);

  return Response.json({ received: true });
}

Güvenli yük şekli

Etkinlik verileri operasyonel meta veriler olarak ele alınmalıdır. Webhook demirbaşlarına veya günlüklerine istemleri, ham API anahtarlarını, ödeme kartı verilerini veya müşteri sırlarını koymayın.

{
  "id": "evt_example_123",
  "type": "usage.threshold_reached",
  "created": "2026-07-06T12:00:00.000Z",
  "data": {
    "workspaceId": "workspace_example",
    "metric": "requests",
    "thresholdPercent": 80
  }
}

Yeniden denemeler

Tekrarlanan teslimat girişimlerine yönelik tasarım.

Webhook gönderimi etkinleştirildiğinde ağ arızaları, zaman aşımları ve 2xx dışı yanıtlar yeniden deneme girişimlerine yol açabilir. Yan etkileri çoğaltmadan aynı olayı birden fazla kez alabilen işleyiciler oluşturun.

Dayanıklı çalışmadan sonra 2xx'i iade edin

Başarıyı döndürmeden önce olay kimliğini yazın veya işi sıraya alın.

Bağımsızlık için olay kimliklerini kullanın

Halihazırda kaydedilmiş veya işlenmiş kopyaları dikkate almayın.

İşleyicileri hızlı tutun

E-postayı, fatura senkronizasyonunu ve uzun işleri dahili bir kuyruğa taşıyın.

Kesin sıralamaya bağlı kalmayın

Olayların sırayla geldiğini varsaymak yerine, mümkün olduğunda mevcut kaynak durumunu kullanın.

gözlemlenebilirlik

Düzenlenmiş uç nokta bağlamı içiçinde plan yapın.

Teslimat kayıtlarını olay türü, uç nokta, durum, deneme sayısı, yanıt durumu, yanıt gövdesi, sonraki yeniden deneme süresi ve teslimat süresi gibi düzeltilmiş operasyonel bağlam çerçevesinde planlayın.

Üretim uç noktası URL'leri için HTTPS zorunlu kılın.

Yüke güvenmeden önce zaman damgalı HMAC imzasını doğrulayın.

İmzalama sırlarını kaynak kodunda değil gizli bir yöneticide saklayın.

Teslim girişimleri tekrarlanabileceğinden, olay işleyicilerine önemsiz davranın.

2xx'i yalnızca olay güvenli bir şekilde kaydedildikten veya kasıtlı olarak göz ardı edildikten sonra döndürün.

Ham imzalama sırlarını, API anahtarlarını, ödeme ayrıntılarını, istemleri veya müşteri verilerini günlüğe kaydetmeyin.

Yerel testler

Üretimden önce tünel ile test edin.

Geliştirme web kancası uç noktasını geçici bir tünele yönlendirin, güvenli bir olay fikstürü hazırlayın, imza yardımcısını doğrulayın ve işleyicinizin tek bir olay kaydını sakladığını doğrulayın.

# Use a local tunnel URL as the endpoint while testing.
https://your-tunnel.example/api/unlimitedcodex/webhook

# Keep the signing secret out of source code.
UCX_WEBHOOK_SECRET=whsec_ucx_placeholder_value

SSS

Web kancası kurulum soruları.

Hangi etkinliklere abone olabilirim?

Müşteri web kancası uç noktası yönetimi, kullanım.threshold_reached, abonelik.updated, api_key.revoked, bill.ücretli ve fatura.payment_failed seçeneklerinin seçilmesini destekler, böylece alıcılar webhook gönderimi etkinleştirilmeden önce yapılandırılabilir.

Webhook teslimatları nasıl imzalanır?

Alıcıları zaman damgalı bir HMAC SHA-256 imzası için hazırlayın. İmza değeri t=timestamp,v1=signature biçimini takip eder ve alıcıların bunu ham istek gövdesine ve imzalama sırrına göre doğrulaması gerekir.

İşleyicimin hangi teslimat varsayımlarını yapması gerekir?

Webhook gönderimi etkinleştirildiğinde tek bir teslimat, katı sipariş veya başarılı bir son deneme olduğunu varsaymayın. Yan etkilerden önce bağımsız işleyiciler oluşturun ve olay kimliklerini kaydedin.

Webhook imzalama sırrını döndürebilir miyim?

Evet. Bir uç noktanın döndürülmesi, bir kez gösterilen yeni bir imzalama sırrı oluşturur. Yeni değeri güvenli bir şekilde saklayın ve üretimde buna bağlı kalmadan önce alıcıyı güncelleyin.

Ücretsiz araçlar

Web kancası alıcı başlatıcıları oluşturun

Faturalandırma veya kullanım olaylarını etkinleştirmeden önce iskele işleyicileri, env dosyaları, kapsamlı anahtarlar ve yeniden deneme güvenliği modelleri.

Tüm araçlara göz atın

Web Kancası Oluşturucu

unlimitedcodex olayları için imza doğrulamasıyla Node veya Python web kancası işleyicileri oluşturun.

Ortam Kurulumu

Seçilen uç noktalardan, ortamdan ve web kancası ihtiyaçlarından.env.example blokları oluşturun.

Kapsam Yapılandırıcı

İş yüklerini seçin ve en az ayrıcalıklı kapsamların,.env.example'ın ve rotasyon kontrol listesinin çıktısını alın.

Simülatörü Yeniden Dene

Simüle edilmiş sonuçları görmek ve yeniden deneme işleyicisi pasajını kopyalamak için geri alma ve yeniden deneme ayarlarını yapın.

Etkinlik alıcılarını hazırlamaya hazır mısınız?

Web kancalarını kullanım ve faturalandırma kontrolleriyle eşleştirin.

Müşteri olayı iş akışları müşteriye yönelik sistemleri etkilemeden önce paket uyumunu, hız sınırı davranışını ve hata işlemeyi gözden geçirin.

Paketleri karşılaştır Hata işlemeyi gözden geçirin