Webhooks

Usher kan fortelle serverne dine hva som skjer i et miljø idet det skjer: noen blir med, logger på, endrer opplysningene sine eller går. Hver hendelse er en signert POST til en adresse du velger, og prøves på nytt hvis serveren din ikke svarer.

Legg til et endepunkt

I Usher Console åpner du miljøet og deretter Webhooks → Nytt endepunkt. Oppgi en https://-adresse du eier, og velg hendelsene den skal få vite om. Console viser signeringshemmeligheten til endepunktet (whsec_…) én gang: oppbevar den sammen med serverens andre hemmeligheter.

Send en test sender en webhook.test-hendelse bare til det endepunktet, uansett hva det abonnerer på.

Hva som kommer fram

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

Hendelser beskriver personer og økter, aldri hemmeligheter: ingen tokener, ingen passordhasjer, ingen roller, og ikke hvorfor noen ble utestengt.

Sjekk hver levering

Usher signerer etter Standard Webhooks-spesifikasjonen, så alle bibliotekene for den sjekker signaturen for deg. Avvis alt som ikke kan verifiseres. Bibliotekene avviser også et tidsstempel som avviker mer enn fem minutter, så en gammel levering ikke kan spilles av på nytt.

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

• Svar innen 15 sekunder med en hvilken som helst 2xx. Alt annet, også en omdirigering, regnes som en feil.
• Regn med gjentakelser. En melding beholder sin webhook-id ved hvert forsøk; hopp over en du allerede har håndtert.
• Ikke stol på rekkefølgen. Nye forsøk kan komme etter nyere hendelser.

Når serveren din ikke svarer

Usher prøver igjen etter 5 sekunder, 5 minutter, 30 minutter, 2 timer, 5 timer, 10 timer og 10 timer til (omtrent halvannet døgn totalt), og gir deretter opp. Leveringsloggen i Console viser alle forsøkene for hver melding og serverens siste svar, og Send på nytt starter leveringen forfra.

En ny hemmelighet

Ny hemmelighet i Console lager en til og viser den én gang. De neste 24 timene har hver levering to signaturer, én per hemmelighet, så du kan ta i bruk den nye hemmeligheten uten å gå glipp av noe. Etter det signerer bare den nye.

Hvor leveringene kommer fra

Webhooks forlater Usher gjennom den utgående proxyen, som ikke kobler til private eller interne adresser. Et endepunkt må være en https://-adresse på et offentlig navn: ikke en IP-adresse, et privat navn eller en adresse på Ushers egne domener.