Webhooki

Usher może na bieżąco informować Twoje serwery o tym, co dzieje się w środowisku: ktoś dołącza, loguje się, zmienia swoje dane lub odchodzi. Każde zdarzenie to podpisane żądanie POST na wybrany przez Ciebie adres, ponawiane, jeśli Twój serwer nie odpowie.

Dodaj punkt końcowy

W Usher Console otwórz środowisko, a następnie wybierz Webhooki → Nowy punkt końcowy. Podaj swój adres https:// i wybierz zdarzenia, o których ma być powiadamiany. Console pokazuje sekret podpisywania punktu końcowego (whsec_…) tylko raz: przechowuj go razem z innymi sekretami serwera.

Wyślij test wysyła zdarzenie webhook.test tylko do tego punktu końcowego, niezależnie od tego, jakie zdarzenia subskrybuje.

Co przychodzi

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

Zdarzenia opisują osoby i sesje, nigdy sekrety: nie zawierają tokenów, skrótów haseł, ról ani powodu, dla którego ktoś został zablokowany.

Sprawdzaj każde dostarczenie

Usher podpisuje zdarzenia zgodnie ze specyfikacją Standard Webhooks, więc każda z jej bibliotek sprawdzi podpis za Ciebie. Odrzucaj wszystko, czego nie da się zweryfikować. Biblioteki odrzucają też znacznik czasu, który różni się o ponad pięć minut, więc starego dostarczenia nie da się powtórzyć.

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

• Odpowiadaj w ciągu 15 sekund dowolnym kodem 2xx. Wszystko inne, także przekierowanie, jest traktowane jako niepowodzenie.
• Spodziewaj się powtórzeń. Wiadomość zachowuje swój webhook-id przy każdej próbie; pomijaj te, które już zostały obsłużone.
• Nie polegaj na kolejności. Ponowienia mogą dotrzeć po nowszych zdarzeniach.

Gdy Twój serwer nie odpowiada

Usher ponawia próbę po 5 sekundach, 5 minutach, 30 minutach, 2 godzinach, 5 godzinach, 10 godzinach i kolejnych 10 godzinach (łącznie około półtora dnia), a potem rezygnuje. Dziennik dostarczeń w Console pokazuje wszystkie próby każdej wiadomości i ostatnią odpowiedź Twojego serwera, a Wyślij ponownie rozpoczyna dostarczanie od nowa.

Nowy sekret

Nowy sekret w Console tworzy kolejny sekret i pokazuje go tylko raz. Przez następne 24 godziny każde dostarczenie ma dwa podpisy, po jednym dla każdego sekretu, więc możesz wdrożyć nowy sekret, niczego nie tracąc. Potem podpisuje już tylko nowy.

Skąd przychodzą dostarczenia

Webhooki opuszczają platformę Usher przez jej serwer proxy ruchu wychodzącego, który nie łączy się z adresami prywatnymi ani wewnętrznymi. Punkt końcowy musi być adresem https:// z nazwą publiczną: nie może to być adres IP, nazwa prywatna ani adres w domenach samego Usher.