Webhooks

Usher kan fortælle dine servere, hvad der sker i et miljø, mens det sker: nogen kommer til, logger ind, ændrer sine oplysninger eller forlader det. Hver hændelse er en signeret POST til en adresse, du vælger, og den forsøges igen, hvis din server ikke svarer.

Tilføj et slutpunkt

Åbn miljøet i Usher Console, og vælg derefter Webhooks → Nyt slutpunkt. Angiv en https://-adresse hos dig, og vælg de hændelser, slutpunktet skal høre om. Console viser slutpunktets signeringshemmelighed (whsec_…) én gang: gem den sammen med din servers andre hemmeligheder.

Send en test sender en webhook.test-hændelse til netop det slutpunkt, uanset hvad det abonnerer på.

Det kommer frem

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

Hændelser beskriver personer og sessioner, aldrig hemmeligheder: ingen tokens, ingen adgangskodehashes, ingen roller og ikke årsagen til, at nogen blev udelukket.

Tjek hver levering

Usher signerer efter Standard Webhooks-specifikationen, så ethvert af dens biblioteker tjekker signaturen for dig. Afvis alt, der ikke kan verificeres. Bibliotekerne afviser også et tidsstempel, der ligger mere end fem minutter væk, så en gammel levering ikke kan genafspilles.

// 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 inden for 15 sekunder med en hvilken som helst 2xx. Alt andet, også en omdirigering, tæller som en fejl.
• Regn med gentagelser. En besked beholder sit webhook-id ved hvert forsøg; spring en over, du allerede har håndteret.
• Stol ikke på rækkefølgen. Nye forsøg kan komme efter nyere hændelser.

Når din server ikke svarer

Usher prøver igen efter 5 sekunder, 5 minutter, 30 minutter, 2 timer, 5 timer, 10 timer og 10 timer (omkring halvanden dag i alt) og giver derefter op. Leveringsloggen i Console viser hver beskeds forsøg og din servers seneste svar, og Send igen starter en levering forfra.

En ny hemmelighed

Ny hemmelighed i Console laver en ny og viser den én gang. I de næste 24 timer har hver levering to signaturer, én pr. hemmelighed, så du kan udrulle den nye hemmelighed uden at gå glip af noget. Derefter signerer kun den nye.

Hvor leveringerne kommer fra

Webhooks forlader Usher gennem dens egress-proxy, som ikke vil forbinde til private eller interne adresser. Et slutpunkt skal være en https://-adresse på et offentligt navn: ikke en IP-adresse, et privat navn eller en adresse på Ushers egne domæner.