Webhookok

Az Usher szól a szervereidnek, mi történik egy környezetben, abban a pillanatban, ahogy megtörténik: valaki csatlakozik, bejelentkezik, módosítja az adatait vagy távozik. Minden esemény egy aláírt POST kérés egy általad választott címre, amelyet az Usher újrapróbál, ha a szervered nem válaszol.

Végpont hozzáadása

Az Usher Console-ban nyisd meg a környezetet, majd válaszd a Webhookok → Új végpont lehetőséget. Adj meg egy saját https:// címet, és válaszd ki, mely eseményekről értesüljön. A Console egyszer megmutatja a végpont aláírási titkos kulcsát (whsec_…): tárold a szervered többi titkos kulcsa mellett.

A Teszt küldése egy webhook.test eseményt küld csak annak a végpontnak, függetlenül attól, mire iratkozott fel.

Mi érkezik

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"
    }
  }
}

Az események embereket és munkameneteket írnak le, soha nem titkokat: nincsenek bennük tokenek, jelszó-hashek, szerepkörök, és az sem, hogy valakit miért tiltottak ki.

Ellenőrizz minden kézbesítést

Az Usher a Standard Webhooks specifikáció szerint ír alá, így bármelyik könyvtára ellenőrzi helyetted az aláírást. Utasíts el mindent, ami nem megy át az ellenőrzésen. A könyvtárak az öt percnél többel eltérő időbélyeget is elutasítják, így egy régi kézbesítést nem lehet visszajátszani.

// 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 })
}

• Válaszolj 15 másodpercen belül bármilyen 2xx kóddal. Minden más, az átirányítást is beleértve, hibának számít.
• Számíts ismétlésekre. Egy üzenet minden kísérletnél megtartja a webhook-id azonosítóját; hagyd ki azt, amelyet már feldolgoztál.
• Ne számíts a sorrendre. Az újrapróbálások újabb események után is megérkezhetnek.

Ha a szervered nem válaszol

Az Usher 5 másodperc, 5 perc, 30 perc, 2 óra, 5 óra, 10 óra és újabb 10 óra múlva próbálkozik újra (összesen körülbelül másfél napig), aztán feladja. A Console kézbesítési naplója minden üzenetnél megmutatja a kísérleteket és a szervered utolsó válaszát, az Újraküldés pedig elölről kezdi a kézbesítést.

Új titkos kulcs

A Console Új titkos kulcs gombja létrehoz egy újat, és egyszer megmutatja. A következő 24 órában minden kézbesítés két aláírást visz, titkos kulcsonként egyet, így anélkül telepítheted az újat, hogy bármiről lemaradnál. Ezután már csak az új ír alá.

Honnan érkeznek a kézbesítések

A webhookok az Usher kimenő proxyján keresztül hagyják el az Ushert, amely nem kapcsolódik privát vagy belső címekhez. Egy végpontnak nyilvános néven lévő https:// címnek kell lennie: nem lehet IP-cím, privát név, sem az Usher saját domainjein lévő cím.