Webhooks

Usher kan je servers laten weten wat er in een omgeving gebeurt, op het moment dat het gebeurt: iemand registreert zich, logt in, wijzigt zijn gegevens of vertrekt. Elke gebeurtenis is een ondertekende POST naar een adres dat jij kiest, die opnieuw wordt geprobeerd als je server niet antwoordt.

Voeg een eindpunt toe

Open in Usher Console de omgeving en kies Webhooks → Nieuw eindpunt. Geef een https://-adres van jezelf op en kies over welke gebeurtenissen het moet horen. Console toont het ondertekeningsgeheim van het eindpunt (whsec_…) één keer: bewaar het bij de andere geheimen van je server.

Stuur een test stuurt een webhook.test-gebeurtenis naar alleen dat eindpunt, ongeacht waarop het is geabonneerd.

Wat er binnenkomt

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

Gebeurtenissen beschrijven mensen en sessies, nooit geheimen: geen tokens, geen wachtwoordhashes, geen rollen, en niet waarom iemand is geblokkeerd.

Controleer elke levering

Usher ondertekent volgens de Standard Webhooks-specificatie, dus elk van de bibliotheken daarvan controleert de handtekening voor je. Weiger alles wat niet klopt. De bibliotheken weigeren ook een tijdstempel die meer dan vijf minuten afwijkt, zodat een oude levering niet opnieuw kan worden afgespeeld.

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

• Antwoord binnen 15 seconden met een 2xx. Al het andere, ook een omleiding, telt als mislukt.
• Reken op herhalingen. Een bericht houdt bij elke poging dezelfde webhook-id; sla een bericht over dat je al hebt verwerkt.
• Ga niet uit van een volgorde. Nieuwe pogingen kunnen binnenkomen na nieuwere gebeurtenissen.

Als je server niet antwoordt

Usher probeert het opnieuw na 5 seconden, 5 minuten, 30 minuten, 2 uur, 5 uur, 10 uur en nog eens 10 uur (bij elkaar ongeveer anderhalve dag), en geeft het daarna op. Het leveringslog in Console toont van elk bericht de pogingen en het laatste antwoord van je server, en met Stuur opnieuw begin je een levering opnieuw.

Een nieuw geheim

Nieuw geheim in Console maakt een ander geheim aan en toont het één keer. De 24 uur daarna draagt elke levering twee handtekeningen, één per geheim, zodat je het nieuwe geheim kunt uitrollen zonder iets te missen. Daarna ondertekent alleen het nieuwe.

Waar leveringen vandaan komen

Webhooks verlaten Usher via de egress-proxy, die geen verbinding maakt met private of interne adressen. Een eindpunt moet een https://-adres zijn op een openbare naam: geen IP-adres, geen private naam en geen adres op de eigen domeinen van Usher.