Webhook’ai

Usher gali pranešti jūsų serveriams, kas vyksta aplinkoje, tą pačią akimirką: kas nors prisiregistruoja, prisijungia, pakeičia savo duomenis ar išeina. Kiekvienas įvykis yra pasirašyta POST užklausa jūsų pasirinktu adresu, kartojama, jei jūsų serveris neatsako.

Pridėkite galinį tašką

Usher Console atidarykite aplinką, tada Webhook’ai → Naujas galinis taškas. Nurodykite savo https:// adresą ir pasirinkite įvykius, apie kuriuos jis turi sužinoti. Console vieną kartą parodo galinio taško pasirašymo paslaptį (whsec_…): laikykite ją kartu su kitomis savo serverio paslaptimis.

Siųsti bandomąjį siunčia webhook.test įvykį tik tam galiniam taškui, kad ir kokius įvykius jis prenumeruotų.

Kas atkeliauja

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

Įvykiai aprašo žmones ir sesijas, niekada ne paslaptis: jokių žetonų, jokių slaptažodžių maišų, jokių vaidmenų ir jokių priežasčių, kodėl kas nors buvo užblokuotas.

Tikrinkite kiekvieną pristatymą

Usher pasirašo pagal Standard Webhooks specifikaciją, todėl bet kuri jos biblioteka patikrina parašą už jus. Atmeskite viską, kas nepraeina patikrinimo. Bibliotekos taip pat atmeta laiko žymą, nutolusią daugiau nei penkias minutes, todėl seno pristatymo negalima pakartoti.

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

• Atsakykite per 15 sekundžių bet kuriuo 2xx. Visa kita, įskaitant peradresavimą, laikoma nesėkme.
• Tikėkitės pasikartojimų. Pranešimas per kiekvieną bandymą išlaiko tą patį webhook-id; praleiskite tą, kurį jau apdorojote.
• Nepasikliaukite tvarka. Pakartotiniai bandymai gali atkeliauti po naujesnių įvykių.

Kai jūsų serveris neatsako

Usher bando dar kartą po 5 sekundžių, 5 minučių, 30 minučių, 2 valandų, 5 valandų, 10 valandų ir dar 10 valandų (iš viso maždaug pusantros paros), tada liaujasi. Console pristatymų žurnale matyti kiekvieno pranešimo bandymai ir paskutinis jūsų serverio atsakymas, o Siųsti dar kartą pradeda pristatymą iš naujo.

Nauja paslaptis

Nauja paslaptis Console sukuria kitą paslaptį ir parodo ją vieną kartą. Kitas 24 valandas kiekvienas pristatymas turi du parašus, po vieną kiekvienai paslapčiai, todėl galite įdiegti naują paslaptį nieko nepraleisdami. Po to pasirašo tik naujoji.

Iš kur atkeliauja pristatymai

Webhook’ai išeina iš Usher per jo išeinančio srauto tarpinį serverį, kuris nesijungia prie privačių ar vidinių adresų. Galinis taškas turi būti https:// adresas su viešu vardu: ne IP adresas, ne privatus vardas ir ne adresas pačios Usher domenuose.