Webhook’lar

Usher, bir ortamda olanları olduğu anda sunucularınıza bildirebilir: biri katılır, giriş yapar, bilgilerini değiştirir ya da ayrılır. Her olay, seçtiğiniz bir adrese gönderilen imzalı bir POST isteğidir ve sunucunuz yanıt vermezse yeniden denenir.

Uç nokta ekleyin

Usher Console’da ortamı açın, ardından Webhook’lar → Yeni uç nokta yolunu izleyin. Size ait bir https:// adresi girin ve hangi olaylardan haberdar olması gerektiğini seçin. Console, uç noktanın imzalama gizli anahtarını (whsec_…) yalnızca bir kez gösterir: onu sunucunuzun diğer gizli bilgileriyle birlikte saklayın.

Test gönder, o uç noktanın hangi olaylara abone olduğundan bağımsız olarak yalnızca ona bir webhook.test olayı gönderir.

Ne gelir?

POST /usher/webhooks HTTP/1.1
content-type: application/json
user-agent: Usher-Webhooks/1
webhook-id: msg_2fk7x…
webhook-timestamp: 1793643116
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

{
  "type": "user.created",
  "timestamp": "2026-11-02T18:11:56.412Z",
  "data": {
    "user": {
      "id": "Qz3m…",
      "email": "lena@acme.com",
      "emailVerified": false,
      "name": "Lena Live",
      "image": null,
      "banned": false,
      "createdAt": "2026-11-02T18:11:56.380Z",
      "updatedAt": "2026-11-02T18:11:56.380Z"
    }
  }
}

Olaylar gizli bilgileri değil, kişileri ve oturumları anlatır: belirteç yok, parola karması yok, rol yok ve birinin neden yasaklandığı da yok.

Her teslimatı denetleyin

Usher, Standard Webhooks belirtimine göre imzalar; bu yüzden onun kütüphanelerinden herhangi biri imzayı sizin için denetler. Doğrulanmayan her şeyi reddedin. Kütüphaneler beş dakikadan daha uzak bir zaman damgasını da reddeder; böylece eski bir teslimat yeniden oynatılamaz.

// a route that receives Usher's webhooks (Node, the standardwebhooks package)
import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.USHER_WEBHOOK_SECRET!) // whsec_…, from Usher Console

export async function POST(request: Request) {
  const body = await request.text() // the raw body: the signature covers it byte for byte
  let event: { type: string; timestamp: string; data: Record<string, unknown> }
  try {
    event = wh.verify(body, Object.fromEntries(request.headers)) as typeof event
  } catch {
    return new Response('bad signature', { status: 400 })
  }
  // webhook-id is the same on every attempt: skip one you have handled already
  if (await alreadyHandled(request.headers.get('webhook-id')!)) return new Response(null, { status: 204 })
  await queue(event) // answer quickly; do the work afterwards
  return new Response(null, { status: 204 })
}

• 15 saniye içinde yanıt verin: herhangi bir 2xx yeterlidir. Yönlendirme dahil diğer her şey başarısızlık sayılır.
• Tekrarlara hazır olun. Bir mesaj her denemede aynı webhook-id değerini taşır; daha önce işlediğinizi atlayın.
• Sıraya güvenmeyin. Yeniden denemeler daha yeni olaylardan sonra gelebilir.

Sunucunuz yanıt vermezse

Usher 5 saniye, 5 dakika, 30 dakika, 2 saat, 5 saat, 10 saat ve 10 saat sonra yeniden dener (toplamda yaklaşık bir buçuk gün), ardından vazgeçer. Console’daki Son teslimatlar listesi her mesajın denemelerini ve sunucunuzun son yanıtını gösterir; Yeniden gönder de teslimatı baştan başlatır.

Yeni bir gizli anahtar

Console’daki Yeni gizli anahtar, yeni bir anahtar oluşturur ve onu bir kez gösterir. Sonraki 24 saat boyunca her teslimat, her anahtar için bir tane olmak üzere iki imza taşır; böylece yeni anahtarı hiçbir şey kaçırmadan dağıtabilirsiniz. Bundan sonra yalnızca yeni anahtar imzalar.

Teslimatlar nereden gelir?

Webhook’lar Usher’dan, özel ya da iç adreslere bağlanmayan çıkış proxy’si üzerinden çıkar. Bir uç nokta, genel bir ad üzerindeki bir https:// adresi olmalıdır: IP adresi, özel bir ad ya da Usher’ın kendi alan adlarından birindeki bir adres olamaz.