Webhooks

Usher kan berätta för dina servrar vad som händer i en miljö medan det händer: någon går med, loggar in, ändrar sina uppgifter eller lämnar. Varje händelse är en signerad POST till en adress du väljer, och den skickas igen om din server inte svarar.

Lägg till en slutpunkt

Öppna miljön i Usher Console och välj sedan Webhooks → Ny slutpunkt. Ange en https://-adress som är din och välj vilka händelser den ska få veta om. Console visar slutpunktens signeringshemlighet (whsec_…) en gång: förvara den tillsammans med serverns övriga hemligheter.

Skicka ett test skickar en webhook.test-händelse till just den slutpunkten, oavsett vilka händelser den prenumererar på.

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

Händelserna beskriver människor och sessioner, aldrig hemligheter: inga tokens, inga lösenordshashar, inga roller och inte varför någon spärrades.

Kontrollera varje leverans

Usher signerar enligt specifikationen Standard Webhooks, så vilket som helst av dess bibliotek kontrollerar signaturen åt dig. Avvisa allt som inte går att verifiera. Biblioteken avvisar också en tidsstämpel som avviker mer än fem minuter, så att en gammal leverans inte kan spelas upp igen.

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

• Svara inom 15 sekunder med valfri 2xx. Allt annat, även en omdirigering, räknas som ett misslyckande.
• Räkna med upprepningar. Ett meddelande behåller sitt webhook-id vid varje försök; hoppa över ett som du redan har hanterat.
• Lita inte på ordningen. Nya försök kan komma fram efter nyare händelser.

När din server inte svarar

Usher försöker igen efter 5 sekunder, 5 minuter, 30 minuter, 2 timmar, 5 timmar, 10 timmar och 10 timmar till (ungefär ett och ett halvt dygn totalt) och ger sedan upp. Leveransloggen i Console visar alla försök för varje meddelande och serverns senaste svar, och Skicka igen startar om en leverans.

En ny hemlighet

Ny hemlighet i Console skapar en ny hemlighet och visar den en gång. Under de följande 24 timmarna har varje leverans två signaturer, en per hemlighet, så att du kan driftsätta den nya hemligheten utan att missa något. Därefter signerar bara den nya.

Var leveranserna kommer ifrån

Webhooks lämnar Usher genom den utgående proxyn, som inte ansluter till privata eller interna adresser. En slutpunkt måste vara en https://-adress med ett publikt namn: inte en IP-adress, ett privat namn eller en adress på Ushers egna domäner.