Webhooks

Usher peut informer vos serveurs de ce qui se passe dans un environnement, au moment où cela se passe : quelqu’un s’inscrit, se connecte, modifie ses informations ou s’en va. Chaque événement est un POST signé envoyé à l’adresse de votre choix, et renvoyé si votre serveur ne répond pas.

Ajouter un point de terminaison

Dans Usher Console, ouvrez l’environnement, puis Webhooks → Nouveau point de terminaison. Indiquez l’une de vos adresses https:// et choisissez les événements qu’elle doit recevoir. La Console affiche une seule fois le secret de signature du point de terminaison (whsec_…) : conservez-le avec les autres secrets de votre serveur.

Envoyer un test envoie un événement webhook.test à ce seul point de terminaison, quels que soient ses abonnements.

Ce qui arrive

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

Les événements décrivent des personnes et des sessions, jamais des secrets : pas de jetons, pas de hachages de mots de passe, pas de rôles, et pas la raison d’un bannissement.

Vérifier chaque livraison

Usher signe selon la spécification Standard Webhooks : n’importe laquelle de ses bibliothèques vérifie donc la signature pour vous. Refusez tout ce qui ne passe pas la vérification. Les bibliothèques refusent aussi un horodatage décalé de plus de cinq minutes, pour qu’une ancienne livraison ne puisse pas être rejouée.

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

• Répondez en moins de 15 secondes avec n’importe quel code 2xx. Toute autre réponse, redirection comprise, compte comme un échec.
• Attendez-vous à des doublons. Un message conserve son webhook-id à chaque tentative ; ignorez ceux que vous avez déjà traités.
• Ne comptez pas sur l’ordre. Des nouvelles tentatives peuvent arriver après des événements plus récents.

Quand votre serveur ne répond pas

Usher réessaie 5 secondes, 5 minutes, 30 minutes, 2 heures, 5 heures, 10 heures et 10 heures plus tard (environ un jour et demi au total), puis abandonne. Le journal des livraisons de la Console montre les tentatives de chaque message et la dernière réponse de votre serveur, et Renvoyer relance une livraison depuis le début.

Un nouveau secret

Nouveau secret dans la Console en génère un autre et ne l’affiche qu’une fois. Pendant les 24 heures suivantes, chaque livraison porte deux signatures, une par secret : vous pouvez ainsi déployer le nouveau secret sans rien manquer. Ensuite, seul le nouveau signe.

D’où viennent les livraisons

Les webhooks quittent Usher par son proxy de sortie, qui refuse de se connecter aux adresses privées ou internes. Un point de terminaison doit être une adresse https:// sur un nom public : pas une adresse IP, pas un nom privé, ni une adresse sur les propres domaines d’Usher.