Webhookovi

Usher može vašim poslužiteljima javiti što se događa u okruženju čim se to dogodi: netko se pridruži, prijavi, promijeni svoje podatke ili ode. Svaki je događaj potpisani POST na adresu koju odaberete, a šalje se ponovno ako vaš poslužitelj ne odgovori.

Dodajte krajnju točku

U sučelju Usher Console otvorite okruženje, a zatim Webhookovi → Nova krajnja točka. Navedite svoju adresu https:// i odaberite događaje o kojima treba saznati. Console tajnu za potpisivanje krajnje točke (whsec_…) prikazuje samo jednom: čuvajte je uz ostale tajne svojeg poslužitelja.

Pošalji test šalje događaj webhook.test samo toj krajnjoj točki, na što god da je pretplaćena.

Što stiže

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

Događaji opisuju ljude i sesije, nikad tajne: nema tokena, nema hasheva lozinki, nema uloga i nema razloga zbog kojeg je netko zabranjen.

Provjerite svaku isporuku

Usher potpisuje prema specifikaciji Standard Webhooks, pa potpis umjesto vas provjerava bilo koja od njezinih biblioteka. Odbijte sve što ne prođe provjeru. Biblioteke odbijaju i vremensku oznaku udaljenu više od pet minuta, pa se stara isporuka ne može ponovno reproducirati.

// 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 u roku od 15 sekundi bilo kojim kôdom 2xx. Sve ostalo, uključujući preusmjeravanje, smatra se neuspjehom.
• Očekujte ponavljanja. Poruka pri svakom pokušaju zadržava svoj webhook-id; preskočite onu koju ste već obradili.
• Ne oslanjajte se na redoslijed. Ponovni pokušaji mogu stići nakon novijih događaja.

Kad vaš poslužitelj ne odgovara

Usher pokušava ponovno nakon 5 sekundi, 5 minuta, 30 minuta, 2 sata, 5 sati, 10 sati i još 10 sati (ukupno oko dan i pol), a zatim odustaje. Zapisnik isporuka u sučelju Console prikazuje sve pokušaje svake poruke i posljednji odgovor vašeg poslužitelja, a Pošalji ponovno pokreće isporuku ispočetka.

Nova tajna

Nova tajna u sučelju Console izrađuje još jednu tajnu i prikazuje je samo jednom. Sljedeća 24 sata svaka isporuka nosi dva potpisa, po jedan za svaku tajnu, pa novu tajnu možete uvesti a da ništa ne propustite. Nakon toga potpisuje samo nova.

Odakle stižu isporuke

Webhookovi izlaze iz platforme Usher kroz njezin izlazni proxy, koji se ne povezuje s privatnim ni internim adresama. Krajnja točka mora biti adresa https:// na javnom nazivu: ne IP adresa, ne privatni naziv i ne adresa na vlastitim domenama platforme Usher.