Webhook

Usher può comunicare ai tuoi server cosa succede in un ambiente nel momento in cui succede: qualcuno si unisce, accede, modifica i propri dati o se ne va. Ogni evento è una POST firmata verso un indirizzo che scegli tu, ritentata se il tuo server non risponde.

Aggiungi un endpoint

In Usher Console, apri l’ambiente, poi Webhook → Nuovo endpoint. Indica un tuo indirizzo https:// e scegli gli eventi che deve ricevere. Console mostra il segreto di firma dell’endpoint (whsec_…) una sola volta: conservalo insieme agli altri segreti del tuo server.

Invia un test invia un evento webhook.test solo a quell’endpoint, a prescindere dagli eventi a cui è iscritto.

Cosa arriva

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

Gli eventi descrivono persone e sessioni, mai segreti: niente token, niente hash delle password, niente ruoli, e nemmeno il motivo per cui qualcuno è stato bloccato.

Verifica ogni consegna

Usher firma secondo la specifica Standard Webhooks, quindi qualsiasi sua libreria verifica la firma al posto tuo. Rifiuta tutto ciò che non supera la verifica. Le librerie rifiutano anche un timestamp che si discosta di più di cinque minuti, così una vecchia consegna non può essere riprodotta.

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

• Rispondi entro 15 secondi con un qualsiasi 2xx. Qualsiasi altra risposta, compreso un reindirizzamento, conta come errore.
• Aspettati ripetizioni. Un messaggio mantiene il suo webhook-id a ogni tentativo; ignora quelli che hai già gestito.
• Non contare sull’ordine. I nuovi tentativi possono arrivare dopo eventi più recenti.

Quando il tuo server non risponde

Usher riprova dopo 5 secondi, 5 minuti, 30 minuti, 2 ore, 5 ore, 10 ore e altre 10 ore (circa un giorno e mezzo in tutto), poi rinuncia. Il registro delle consegne di Console mostra i tentativi di ogni messaggio e l’ultima risposta del tuo server, e Invia di nuovo ricomincia una consegna da capo.

Un nuovo segreto

Nuovo segreto in Console ne crea un altro e lo mostra una sola volta. Per le 24 ore successive ogni consegna porta due firme, una per segreto, così puoi distribuire il nuovo segreto senza perdere nulla. Dopodiché firma solo quello nuovo.

Da dove arrivano le consegne

I webhook escono da Usher attraverso il suo proxy di uscita, che non si collega a indirizzi privati o interni. Un endpoint deve essere un indirizzo https:// su un nome pubblico: non un indirizzo IP, non un nome privato, né un indirizzo sui domini di Usher.