Webhookit

Usher voi kertoa palvelimillesi, mitä ympäristössä tapahtuu, heti kun se tapahtuu: joku liittyy, kirjautuu, muuttaa tietojaan tai lähtee. Jokainen tapahtuma on allekirjoitettu POST-pyyntö valitsemaasi osoitteeseen, ja sitä yritetään uudelleen, jos palvelimesi ei vastaa.

Lisää päätepiste

Avaa Usher Consolessa ympäristö ja sitten Webhookit → Uusi päätepiste. Anna oma https://-osoitteesi ja valitse tapahtumat, joista sen pitää kuulla. Console näyttää päätepisteen allekirjoitussalaisuuden (whsec_…) kerran: säilytä se palvelimesi muiden salaisuuksien kanssa.

Lähetä testi lähettää webhook.test-tapahtuman vain kyseiselle päätepisteelle riippumatta siitä, mitä tapahtumia se tilaa.

Mitä saapuu

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

Tapahtumat kuvaavat ihmisiä ja istuntoja, eivät koskaan salaisuuksia: ei tunnuksia, ei salasanatiivisteitä, ei rooleja eikä sitä, miksi joku estettiin.

Tarkista jokainen toimitus

Usher allekirjoittaa Standard Webhooks -määrityksen mukaisesti, joten mikä tahansa sen kirjastoista tarkistaa allekirjoituksen puolestasi. Hylkää kaikki, mikä ei läpäise tarkistusta. Kirjastot hylkäävät myös aikaleiman, joka poikkeaa nykyhetkestä yli viisi minuuttia, joten vanhaa toimitusta ei voi toistaa.

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

• Vastaa 15 sekunnin kuluessa millä tahansa 2xx-koodilla. Kaikki muu, uudelleenohjaus mukaan lukien, lasketaan epäonnistumiseksi.
• Varaudu toistoihin. Viesti säilyttää webhook-id-tunnisteensa jokaisella yrityksellä; ohita viesti, jonka olet jo käsitellyt.
• Älä luota järjestykseen. Uudelleenyritykset voivat saapua uudempien tapahtumien jälkeen.

Kun palvelimesi ei vastaa

Usher yrittää uudelleen 5 sekunnin, 5 minuutin, 30 minuutin, 2 tunnin, 5 tunnin, 10 tunnin ja vielä 10 tunnin kuluttua (kaikkiaan noin puolentoista vuorokauden ajan) ja luovuttaa sitten. Consolen toimitusloki näyttää jokaisen viestin yritykset ja palvelimesi viimeisimmän vastauksen, ja Lähetä uudelleen aloittaa toimituksen alusta.

Uusi salaisuus

Uusi salaisuus Consolessa luo toisen salaisuuden ja näyttää sen kerran. Seuraavien 24 tunnin ajan jokaisessa toimituksessa on kaksi allekirjoitusta, yksi kummallakin salaisuudella, joten voit ottaa uuden salaisuuden käyttöön menettämättä mitään. Sen jälkeen allekirjoittaa vain uusi salaisuus.

Mistä toimitukset tulevat

Webhookit lähtevät Usherista sen lähtevän liikenteen välityspalvelimen kautta, joka ei yhdistä yksityisiin tai sisäisiin osoitteisiin. Päätepisteen on oltava https://-osoite julkisella nimellä: ei IP-osoite, yksityinen nimi tai osoite Usherin omissa verkkotunnuksissa.