Webhooky

Usher může vašim serverům hlásit, co se v prostředí děje, hned jak se to stane: někdo se připojí, přihlásí, změní své údaje nebo odejde. Každá událost je podepsaný požadavek POST na adresu, kterou zvolíte, a pokud váš server neodpoví, přijde znovu.

Přidejte koncový bod

V Usher Console otevřete prostředí a pak Webhooky → Nový koncový bod. Zadejte svou adresu https:// a vyberte události, o kterých se má dozvídat. Console jednou zobrazí podpisový tajný klíč koncového bodu (whsec_…): uložte ho k ostatním tajným údajům svého serveru.

Odeslat test pošle událost webhook.test jen danému koncovému bodu, ať je přihlášený k odběru čehokoli.

Co přijde

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

Události popisují lidi a relace, nikdy tajné údaje: žádné tokeny, žádné hashe hesel, žádné role a ani důvod, proč byl někdo zablokován.

Kontrolujte každé doručení

Usher podepisuje podle specifikace Standard Webhooks, takže podpis za vás zkontroluje kterákoli z jejích knihoven. Odmítněte všechno, co ověřením neprojde. Knihovny také odmítnou časové razítko vzdálené víc než pět minut, takže staré doručení nejde přehrát znovu.

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

• Odpovězte do 15 sekund libovolným kódem 2xx. Cokoli jiného, včetně přesměrování, se počítá jako selhání.
• Počítejte s opakováním. Zpráva si při každém pokusu ponechá stejné webhook-id; tu, kterou už jste zpracovali, přeskočte.
• Nespoléhejte na pořadí. Opakované pokusy mohou dorazit až po novějších událostech.

Když váš server neodpovídá

Usher to zkusí znovu za 5 sekund, 5 minut, 30 minut, 2 hodiny, 5 hodin, 10 hodin a 10 hodin (celkem asi den a půl) a pak to vzdá. Seznam nedávných doručení v Console ukazuje pokusy u každé zprávy a poslední odpověď vašeho serveru a tlačítko Odeslat znovu spustí doručení od začátku.

Nový tajný klíč

Tlačítko Nový tajný klíč v Console vytvoří další klíč a jednou ho zobrazí. Následujících 24 hodin nese každé doručení dva podpisy, jeden za každý klíč, takže můžete nový klíč nasadit, aniž byste o něco přišli. Potom podepisuje už jen nový.

Odkud doručení přicházejí

Webhooky opouštějí Usher přes jeho odchozí proxy, která se nepřipojí na soukromé ani interní adresy. Koncový bod musí být adresa https:// s veřejným názvem: ne IP adresa, soukromý název ani adresa na vlastních doménách služby Usher.