Spletni kljuki

Usher lahko vašim strežnikom sporoči, kaj se dogaja v okolju, takoj ko se zgodi: nekdo se pridruži, se prijavi, spremeni svoje podatke ali odide. Vsak dogodek je podpisan POST na naslov, ki ga izberete, in se ponovi, če vaš strežnik ne odgovori.

Dodajte končno točko

V Usher Console odprite okolje, nato Spletni kljuki → Nova končna točka. Navedite svoj naslov https:// in izberite dogodke, o katerih naj izve. Console skrivnost za podpisovanje končne točke (whsec_…) prikaže enkrat: hranite jo skupaj z drugimi skrivnostmi svojega strežnika.

Pošlji preizkus pošlje dogodek webhook.test samo tej končni točki, ne glede na to, na kaj je naročena.

Kaj prispe

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

Dogodki opisujejo ljudi in seje, nikoli skrivnosti: brez žetonov, brez zgoščenih vrednosti gesel, brez vlog in brez razloga, zakaj je bil nekdo prepovedan.

Preverite vsako dostavo

Usher podpisuje po specifikaciji Standard Webhooks, zato podpis namesto vas preveri katera koli od njenih knjižnic. Zavrnite vse, kar ne prestane preverjanja. Knjižnice zavrnejo tudi časovni žig, ki odstopa za več kot pet minut, zato stare dostave ni mogoče ponoviti.

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

• Odgovorite v 15 sekundah s katerim koli 2xx. Vse drugo, tudi preusmeritev, šteje kot neuspeh.
• Pričakujte ponovitve. Sporočilo ob vsakem poskusu ohrani svoj webhook-id; tistega, ki ste ga že obdelali, preskočite.
• Ne zanašajte se na vrstni red. Ponovni poskusi lahko prispejo za novejšimi dogodki.

Ko vaš strežnik ne odgovori

Usher poskusi znova 5 sekund, 5 minut, 30 minut, 2 uri, 5 ur, 10 ur in 10 ur pozneje (skupno približno dan in pol), nato odneha. Dnevnik dostav v Console prikaže poskuse vsakega sporočila in zadnji odgovor vašega strežnika, Pošlji znova pa dostavo začne od začetka.

Nova skrivnost

Nova skrivnost v Console ustvari novo skrivnost in jo prikaže enkrat. Naslednjih 24 ur vsaka dostava nosi dva podpisa, po enega za vsako skrivnost, zato lahko novo skrivnost uvedete, ne da bi kaj zamudili. Nato podpisuje samo nova.

Od kod prihajajo dostave

Spletni kljuki zapustijo Usher skozi njegov izhodni posredniški strežnik, ki se ne poveže na zasebne ali notranje naslove. Končna točka mora biti naslov https:// na javnem imenu: ne naslov IP, ne zasebno ime in ne naslov na Usherjevih domenah.