Webhooky

Usher môže vašim serverom oznamovať, čo sa v prostredí deje, hneď ako sa to deje: niekto sa pridá, prihlási, zmení svoje údaje alebo odíde. Každá udalosť je podpísaná požiadavka POST na adresu, ktorú si zvolíte, a ak váš server neodpovie, odošle sa znova.

Pridajte koncový bod

V Usher Console otvorte prostredie a potom Webhooky → Nový koncový bod. Zadajte svoju adresu https:// a zvoľte udalosti, o ktorých sa má dozvedať. Console raz zobrazí podpisový tajný kód koncového bodu (whsec_…): uložte ho k ostatným tajným údajom svojho servera.

Poslať test pošle udalosť webhook.test len tomuto koncovému bodu bez ohľadu na to, na čo je prihlásený.

Čo príde

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

Udalosti opisujú ľudí a relácie, nikdy tajné údaje: žiadne tokeny, žiadne haše hesiel, žiadne roly a ani dôvod, prečo bol niekto zablokovaný.

Overte každé doručenie

Usher podpisuje podľa špecifikácie Standard Webhooks, takže podpis za vás overí ktorákoľvek z jej knižníc. Odmietnite všetko, čo overením neprejde. Knižnice odmietnu aj časovú pečiatku vzdialenú viac než päť minút, takže staré doručenie sa nedá zopakovať.

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

• Odpovedzte do 15 sekúnd akýmkoľvek kódom 2xx. Čokoľvek iné, vrátane presmerovania, sa počíta ako zlyhanie.
• Rátajte s opakovaním. Správa si pri každom pokuse zachová svoje webhook-id; tú, ktorú ste už spracovali, preskočte.
• Nespoliehajte sa na poradie. Opakované pokusy môžu prísť po novších udalostiach.

Keď váš server neodpovedá

Usher to skúsi znova o 5 sekúnd, 5 minút, 30 minút, 2 hodiny, 5 hodín, 10 hodín a 10 hodín (celkovo asi deň a pol) a potom to vzdá. Denník doručení v Console ukazuje pokusy pri každej správe a poslednú odpoveď vášho servera a tlačidlo Poslať znova spustí doručenie odznova.

Nový tajný kód

Nový tajný kód v Console vytvorí ďalší tajný kód a raz ho zobrazí. Nasledujúcich 24 hodín nesie každé doručenie dva podpisy, jeden pre každý tajný kód, takže nový tajný kód môžete nasadiť bez toho, aby vám niečo ušlo. Potom podpisuje už len nový.

Odkiaľ doručenia prichádzajú

Webhooky odchádzajú zo služby Usher cez jej výstupný proxy server, ktorý sa nepripojí na súkromné ani interné adresy. Koncový bod musí byť adresa https:// na verejnom názve: nie IP adresa, súkromný názov ani adresa na vlastných doménach služby Usher.